From 09a4bc4944f38824b387386a1d6e03f99933a62f Mon Sep 17 00:00:00 2001 From: "Carrie Warner (Mattermost)" <74422101+cwarnermm@users.noreply.github.com> Date: Fri, 25 Oct 2024 16:13:31 -0400 Subject: [PATCH 1/3] Archived legacy pages & added page redirects (#7511) --- source/about/mobile-app-changelog.md | 2 +- source/about/orchestration.rst | 91 - source/collaborate/format-messages.rst | 264 +- source/collaborate/learn-about-roles.rst | 7 +- source/collaborate/syntax-highlighting.rst | 261 -- source/conf.py | 89 +- source/configure/calls-deployment.rst | 2 +- .../common-config-settings-notation.rst | 9 - .../database-configuration-settings.rst | 609 --- .../developer-mode-configuration-settings.rst | 150 - .../elasticsearch-configuration-settings.rst | 770 ---- source/configure/enable-copilot.rst | 2 +- .../environment-configuration-settings.rst | 4019 ++++++++++++++++- .../experimental-configuration-settings.rst | 12 +- .../file-storage-configuration-settings.rst | 515 --- ...gh-availability-configuration-settings.rst | 282 -- .../image-proxy-configuration-settings.rst | 100 - .../logging-configuration-settings.rst | 348 -- source/configure/optimize-your-workspace.rst | 2 +- ...ance-monitoring-configuration-settings.rst | 57 - .../plugins-configuration-settings.rst | 4 +- ...session-lengths-configuration-settings.rst | 200 - .../configure/smtp-configuration-settings.rst | 211 - source/configure/smtp-email.rst | 2 - .../web-server-configuration-settings.rst | 726 --- source/deploy/mobile-troubleshoot.rst | 2 +- source/install/common-deploy-faq.rst | 2 + source/install/common-local-deploy-docker.rst | 29 - source/install/common-prod-deploy-docker.rst | 113 - source/install/common-prod-deploy-omnibus.rst | 55 - source/install/common-prod-deploy-tar.rst | 186 - source/install/config-mattermost-server.rst | 55 - source/install/config-proxy-nginx.rst | 132 - source/install/config-ssl-http2-nginx.rst | 201 - source/install/faq_kubernetes.rst | 66 - source/install/install-common-intro.rst | 13 - source/install/install-debian-mysql.rst | 65 - source/install/install-debian-postgresql.rst | 109 - source/install/install-debian-server.rst | 24 - source/install/install-debian.rst | 145 - source/install/install-docker.rst | 110 +- source/install/install-kubernetes.rst | 65 +- source/install/install-nginx.rst | 79 - source/install/install-rhel-nginx.rst | 58 - source/install/setup-mattermost-server.rst | 2 + source/install/setup-nginx-proxy.rst | 402 +- .../install/trial-mattermost-using-docker.rst | 26 +- source/manage/bulk-export-data.rst | 757 ---- source/manage/bulk-export-tool.rst | 757 +++- source/manage/common-support-packet.rst | 135 - source/manage/generating-support-packet.rst | 135 +- source/onboard/bulk-loading-about.rst | 24 - source/onboard/bulk-loading-common-issues.rst | 13 - source/onboard/bulk-loading-data-format.rst | 1522 ------- source/onboard/bulk-loading-data.rst | 1593 ++++++- .../onboard/bulk-loading-troubleshooting.rst | 14 - source/onboard/common-disable-mfa.rst | 8 - source/onboard/common-sso-entraid.rst | 76 - source/onboard/common-sso-google.rst | 63 - source/onboard/common-sso-openidconnect.rst | 36 - source/onboard/guest-account-access.rst | 18 - source/onboard/guest-accounts.rst | 17 +- .../onboard/multi-factor-authentication.rst | 8 +- source/onboard/run-bulk-loading-command.rst | 24 - source/onboard/sso-entraid.rst | 75 +- source/onboard/sso-google.rst | 62 +- source/onboard/sso-openidconnect.rst | 36 +- source/onboard/sso-saml-before-you-begin.rst | 3 + source/onboard/sso-saml-faq.rst | 3 + ...-availability-cluster-based-deployment.rst | 2 +- 70 files changed, 7589 insertions(+), 8465 deletions(-) delete mode 100644 source/about/orchestration.rst delete mode 100644 source/collaborate/syntax-highlighting.rst delete mode 100644 source/configure/common-config-settings-notation.rst delete mode 100644 source/configure/database-configuration-settings.rst delete mode 100644 source/configure/developer-mode-configuration-settings.rst delete mode 100644 source/configure/elasticsearch-configuration-settings.rst delete mode 100644 source/configure/file-storage-configuration-settings.rst delete mode 100644 source/configure/high-availability-configuration-settings.rst delete mode 100644 source/configure/image-proxy-configuration-settings.rst delete mode 100644 source/configure/logging-configuration-settings.rst delete mode 100644 source/configure/performance-monitoring-configuration-settings.rst delete mode 100644 source/configure/session-lengths-configuration-settings.rst delete mode 100644 source/configure/smtp-configuration-settings.rst delete mode 100644 source/configure/web-server-configuration-settings.rst delete mode 100644 source/install/common-local-deploy-docker.rst delete mode 100644 source/install/common-prod-deploy-docker.rst delete mode 100644 source/install/common-prod-deploy-omnibus.rst delete mode 100644 source/install/common-prod-deploy-tar.rst delete mode 100644 source/install/config-mattermost-server.rst delete mode 100644 source/install/config-proxy-nginx.rst delete mode 100644 source/install/config-ssl-http2-nginx.rst delete mode 100644 source/install/faq_kubernetes.rst delete mode 100644 source/install/install-common-intro.rst delete mode 100644 source/install/install-debian-mysql.rst delete mode 100644 source/install/install-debian-postgresql.rst delete mode 100644 source/install/install-debian-server.rst delete mode 100644 source/install/install-debian.rst delete mode 100644 source/install/install-nginx.rst delete mode 100644 source/install/install-rhel-nginx.rst delete mode 100644 source/manage/bulk-export-data.rst delete mode 100644 source/manage/common-support-packet.rst delete mode 100644 source/onboard/bulk-loading-about.rst delete mode 100644 source/onboard/bulk-loading-common-issues.rst delete mode 100644 source/onboard/bulk-loading-data-format.rst delete mode 100644 source/onboard/bulk-loading-troubleshooting.rst delete mode 100644 source/onboard/common-disable-mfa.rst delete mode 100644 source/onboard/common-sso-entraid.rst delete mode 100644 source/onboard/common-sso-google.rst delete mode 100644 source/onboard/common-sso-openidconnect.rst delete mode 100644 source/onboard/guest-account-access.rst delete mode 100644 source/onboard/run-bulk-loading-command.rst diff --git a/source/about/mobile-app-changelog.md b/source/about/mobile-app-changelog.md index 405a3a35ae2..698964a4d8a 100644 --- a/source/about/mobile-app-changelog.md +++ b/source/about/mobile-app-changelog.md @@ -3847,7 +3847,7 @@ Many thanks to all our contributors. In alphabetical order: - Release Date: March 29, 2017 - Server Versions Supported: Server v3.7+ is required, Self-Signed SSL Certificates are not yet supported -Note: If you need an SSL certificate, consider using [Let's Encrypt](https://docs.mattermost.com/install/config-ssl-http2-nginx.html) instead of a self-signed one. +Note: If you need an SSL certificate, consider using Let's Encrypt instead of a self-signed one. ### Highlights diff --git a/source/about/orchestration.rst b/source/about/orchestration.rst deleted file mode 100644 index 4b525d15465..00000000000 --- a/source/about/orchestration.rst +++ /dev/null @@ -1,91 +0,0 @@ -:orphan: - -Deployment solution programs -============================ - -.. This page is intentionally not accessible via the LHS navigation pane. - -Mattermost's **Deployment Solutions Programs** help IT administrators understand how Mattermost is being offered in third-party deployment solutions, including other open source projects as well as in commercial solutions. - -This is an optional program for third-party developers to increase awareness about their work and to enable Mattermost to refer its communities to different solutions. - -Any person or any company interested in discussing deployment solutions with Mattermost can join the `Deployment Solutions discussion channel `__ on the Mattermost community server to speak to peers and Mattermost community managers. - -Deployment solutions are recognized by Mattermost at three-levels: - -- **Community Deployment Solutions** - Basic orchestration solutions for Mattermost, typically from the open source community or hosting companies who let us know about their work. The work of partners is included in blog posts and on social media as a benefit to the user and customer communities. - - Examples: - - - `Puppet deployment solution for Mattermost `__ by Richard Grainger - - `Heroku deployment solution for Mattermost `__ by Christopher De Cairos - -- **Registered Deployment Solutions** - Orchestration solutions that follow detailed Mattermost guidelines on keeping up-to-date with the latest Mattermost version and security updates (typically a one-line change), linking to official documentation, supporting branding guidelines, and maintaining a changelog. This level of engagement allows Mattermost to more prominently promote the work, knowing that it's committed to meeting explicit standards. - -- **Certified Deployment Solutions** - These solutions meet all the requirements of Registered Deployment Solutions, with the addition that they'll automate the version upgrade and security update processes (typically a one-line change). There is the added benefit that when Mattermost announces new versions and security updates, we can also announce the availability of updates to Certified Deployment Solutions. - -To summarize the commitment level of different solutions: - -================================== ========= =========== =========== -Deployment Solution Requirement Community Registered Certified -================================== ========= =========== =========== -Installation Yes Yes Yes ----------------------------------- --------- ----------- ----------- -Minimum Documentation Yes Yes Yes ----------------------------------- --------- ----------- ----------- -Security Updates Yes Yes ----------------------------------- --------- ----------- ----------- -Branding Yes Yes ----------------------------------- --------- ----------- ----------- -Upgrade Yes -================================== ========= =========== =========== - -Requirement details are outline below: - -Deployment solution program requirements ----------------------------------------- - -Installation -~~~~~~~~~~~~ - -1. **Installation is designed for officially supported operating systems and platforms**. EXCEPTION: RHEL equivalents (CentOS, Amazon Linux, Oracle Linux, Scientific Linux) are acceptable as long as the exception is noted in README or equivalent with ``This deployment uses [OPERATING_SYSTEM] as an equivalent to the officially supported version of Red Hat Enterprise Linux.`` - -2. **Automated installation passes basic testing**. After installation run the following manual tests: - - 1) Create a new user account and use that account to create a new team and post to Town Square channel. - 2) Create a second user account and join the newly created team and reply to first user's post in Town Square. - 3) Go back to first user account and post reply with an image attached. - 4) Confirm there are no errors and no red alert bar at the top of the screen with "Mattermost unreachable error" (which would indicate a websocket configuration error). - -Documentation -~~~~~~~~~~~~~ - -1. **Include link to official Mattermost documentation**. README or equivalent contains statement ``Please see https://docs.mattermost.com for official documentation.`` - - Include the following information in text, markdown, HTML or other format. Square brackets [] indicate optional statements depending on the configuration of your solution: - - This deployment solution installs [and upgrades] a Mattermost server to provide secure, private cloud messaging for teams and enterprises. More information is available at: https://mattermost.com - - Following automated deployment, the following steps are required to make your system production-ready: - - - [Configure SSL for Mattermost](https://docs.mattermost.com/install/config-ssl-http2-nginx.html) - - [Configure SMTP email for Mattermost](https://docs.mattermost.com/configure/smtp-email.html) - -2. **Unofficial deployment options should be documented**. Unofficial deployment configurations, such as use of Linux operating systems that are not officially supported, should be documented in the README. - -Security updates -~~~~~~~~~~~~~~~~ - -1. **Document commitment to providing security updates.** README or equivalent states `We highly recommend users subscribe to the Mattermost security updates email list. When notified of a security update, the maintainers of this deployment solution will make an effort to update to the secure version within 10 days.` - -2. **Commit to making an effort for your deployment to provide the latest security update within 10 days of announcement**. This is typically a one-line change. - -Branding -~~~~~~~~ - -1. **Support Mattermost branding and naming guidelines**. To ensure naming is clear across deployment solutions, README or equivalent should contain ``The name for this deployment solution in the context of [Mattermost branding guidelines](https://handbook.mattermost.com/operations/operations/publishing/publishing-guidelines/brand-and-visual-design-guidelines) is `[NAME] for Mattermost by [CREATOR]`.`` For example, ``Multi-node Docker deployment solution for Mattermost by John Doe``. This is the name that will be used to refer to your work in Mattermost community materials. - -Upgrade -~~~~~~~ - -1. **Support upgrade of Mattermost**. Enable user interface or command line upgrade of a Mattermost deployment to latest version based on `upgrade procedure when Mattermost is embedded `__ diff --git a/source/collaborate/format-messages.rst b/source/collaborate/format-messages.rst index 9fd700d0bd4..4ab7551ff45 100644 --- a/source/collaborate/format-messages.rst +++ b/source/collaborate/format-messages.rst @@ -212,14 +212,272 @@ Or by indenting each line by four spaces: ^^^^ 4x spaces -**Syntax highlighting** +Syntax highlighting +^^^^^^^^^^^^^^^^^^^^ To add syntax highlighting, type the language to be highlighted after the ``````` at the beginning of the code block. Mattermost also offers four different code themes (GitHub, Solarized Dark, Solarized Light, and Monokai) that can be changed in **Settings > Display > Theme > Custom Theme > Center Channel Styles**. Supported languages and their aliases include: -.. include:: syntax-highlighting.rst - :start-after: :nosearch: +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LanguageAliases
ActionScriptactionscript, as, as3
AppleScriptapplescript
Bashbash, sh
Clojureclojure
CoffeeScriptcoffescript, coffee, coffee-script
C/C++cpp, c++, c
C#cs, c#, csharp
CSScss
Dd, dlang
Dartdart
Delphidelphi
Diffdiff, patch, udiff
Djangodjango
Dockerfiledockerfile, docker
Elixirelixir, ex, exs
Erlangerlang, erl
Fortranfortran
F#fsharp
G-Codegcode
Gogo, golang
Groovygroovy
Handlebarshandlebars, hbs, mustache
Haskellhaskell, hs
Haxehaxe
Javajava
JavaScriptjavascript, js
JSONjson
Juliajulia, jl
Kotlinkotlin
LaTeXlatex, tex
Lessless
Lisplisp
Lualua
Makefilemakefile, make, mf, gnumake, bsdmake
Markdownmarkdown, md, mkd
Matlabmatlab, m
Objective Cobjectivec, objective_c, objc
OCamlocaml
Perlperl, pl
Pascalpascal, pas
PostgreSQLpgsql, postgres, postgresql
PHPphp, php3, php4, php5
PowerShellpowershell, posh
Puppetpuppet, pp
Pythonpython, py
Rr, s
Rubyruby, rb
Rustrust, rs
Scalascala
Schemescheme
SCSSscss
Smalltalksmalltalk, st, squeak
SQLsql
Stylusstylus, styl
Swiftswift
Texttext
TypeScripttypescript, ts, tsx
VB.Netvbnet, vb, visualbasic
VBScriptvbscript
Verilogverilog
VHDLvhdl
HTML, XMLhtml, xml
YAMLyaml, yml
Example: diff --git a/source/collaborate/learn-about-roles.rst b/source/collaborate/learn-about-roles.rst index ed4e5cc74de..5316fdb6e21 100644 --- a/source/collaborate/learn-about-roles.rst +++ b/source/collaborate/learn-about-roles.rst @@ -68,12 +68,7 @@ This is the default role given to users when they join a team. Members have basi Guest ----- -A guest is a role with restricted permissions. Guests enable organizations to collaborate with users outside of their organization, and control what channels they are in and who they can collaborate with. - -.. include:: /onboard/guest-account-access.rst - :start-after: :nosearch: - -See the :doc:`guest accounts ` documentation for details on working with guest accounts. +A guest is a role with restricted permissions. Guests enable organizations to collaborate with users outside of their organization, and control what channels they are in and who they can collaborate with. See the :doc:`guest accounts ` documentation for details on working with guest accounts. Deactivated ----------- diff --git a/source/collaborate/syntax-highlighting.rst b/source/collaborate/syntax-highlighting.rst deleted file mode 100644 index 8a9c05bb269..00000000000 --- a/source/collaborate/syntax-highlighting.rst +++ /dev/null @@ -1,261 +0,0 @@ -:nosearch: - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
LanguageAliases
ActionScriptactionscript, as, as3
AppleScriptapplescript
Bashbash, sh
Clojureclojure
CoffeeScriptcoffescript, coffee, coffee-script
C/C++cpp, c++, c
C#cs, c#, csharp
CSScss
Dd, dlang
Dartdart
Delphidelphi
Diffdiff, patch, udiff
Djangodjango
Dockerfiledockerfile, docker
Elixirelixir, ex, exs
Erlangerlang, erl
Fortranfortran
F#fsharp
G-Codegcode
Gogo, golang
Groovygroovy
Handlebarshandlebars, hbs, mustache
Haskellhaskell, hs
Haxehaxe
Javajava
JavaScriptjavascript, js
JSONjson
Juliajulia, jl
Kotlinkotlin
LaTeXlatex, tex
Lessless
Lisplisp
Lualua
Makefilemakefile, make, mf, gnumake, bsdmake
Markdownmarkdown, md, mkd
Matlabmatlab, m
Objective Cobjectivec, objective_c, objc
OCamlocaml
Perlperl, pl
Pascalpascal, pas
PostgreSQLpgsql, postgres, postgresql
PHPphp, php3, php4, php5
PowerShellpowershell, posh
Puppetpuppet, pp
Pythonpython, py
Rr, s
Rubyruby, rb
Rustrust, rs
Scalascala
Schemescheme
SCSSscss
Smalltalksmalltalk, st, squeak
SQLsql
Stylusstylus, styl
Swiftswift
Texttext
TypeScripttypescript, ts, tsx
VB.Netvbnet, vb, visualbasic
VBScriptvbscript
Verilogverilog
VHDLvhdl
HTML, XMLhtml, xml
YAMLyaml, yml
\ No newline at end of file diff --git a/source/conf.py b/source/conf.py index bc26e2db36a..8467cc4420e 100644 --- a/source/conf.py +++ b/source/conf.py @@ -129,6 +129,8 @@ def setup(_: Sphinx): "https://docs.mattermost.com/maximize-microsoft-investment.html", "about/install-mattermost-for-microsoft-teams-plugin.html": "https://docs.mattermost.com/integrate/microsoft-teams-interoperability.html", +"about/orchestration.html": + "https://docs.mattermost.com/about/use-cases.html", # Administration redirects "administration/announcement-banner.html": @@ -855,6 +857,8 @@ def setup(_: Sphinx): "https://docs.mattermost.com/collaborate/organize-conversations.html#enable-threaded-discussions", "collaborate/collaborate-within-embedded-microsoft-teams.html": "https://docs.mattermost.com/integrate/microsoft-teams-interoperability.html", +"collaborate/syntax-highlighting.html": + "https://docs.mattermost.com/collaborate/format-messages.html#syntax-highlighting", # Compliance redirects "comply/compliance-reporting-oversight": @@ -871,6 +875,18 @@ def setup(_: Sphinx): "https://forum.mattermost.com/t/configuring-apache2-as-a-proxy-for-mattermost-server/11938", "configure/enable-ai-copilot.html": "https://docs.mattermost.com/enable-copilot.html", +"configure/common-config-settings-notation.html": + "https://docs.mattermost.com/configure/configuration-settings.html", +"configure/bulk-loading-about.html": + "https://docs.mattermost.com/onboard/bulk-loading-data.html", +"configure/bulk-loading-common-issues.html": + "https://docs.mattermost.com/onboard/bulk-loading-data.html", +"configure/bulk-loading-data-format.html": + "https://docs.mattermost.com/onboard/bulk-loading-data.html", +"configure/bulk-loading-troubleshooting.html": + "https://docs.mattermost.com/onboard/bulk-loading-data.html", +"configure/run-bulk-loading-command.html": + "https://docs.mattermost.com/onboard/bulk-loading-data.html", # Configuration settings redirects "configure/configuration-in-mattermost-database.html": @@ -1849,6 +1865,28 @@ def setup(_: Sphinx): "https://docs.mattermost.com/configure/configuration-in-your-database.html", "configure/install-mattermost-for-microsoft-teams-plugin.html": "https://docs.mattermost.com/integrate/microsoft-teams-interoperability.html#install-and-configure-the-microsoft-teams-integration-in-mattermost", +"configure/developer-mode-configuration-settings.html": + "https://docs.mattermost.com/configure/environment-configuration-settings.html#developer", +"configure/performance-monitoring-configuration-settings.html": + "https://docs.mattermost.com/configure/environment-configuration-settings.html#performance-monitoring", +"configure/session-lengths-configuration-settings.html": + "https://docs.mattermost.com/configure/environment-configuration-settings.html#session-lengths", +"configure/logging-configuration-settings.html": + "https://docs.mattermost.com/configure/environment-configuration-settings.html#logging", +"configure/high-availability-configuration-settings.html": + "https://docs.mattermost.com/configure/environment-configuration-settings.html#high-availability", +"configure/smtp-configuration-settings.html": + "https://docs.mattermost.com/configure/environment-configuration-settings.html#smtp", +"configure/file-storage-configuration-settings.html": + "https://docs.mattermost.com/configure/environment-configuration-settings.html#file-storage", +"configure/web-server-configuration-settings.html": + "https://docs.mattermost.com/configure/environment-configuration-settings.html#web-server", +"configure/image-proxy-configuration-settings.html": + "https://docs.mattermost.com/configure/environment-configuration-settings.html#image-proxy", +"configure/elasticsearch-configuration-settings.html": + "https://docs.mattermost.com/configure/environment-configuration-settings.html#elasticsearch", +"configure/database-configuration-settings": + "https://docs.mattermost.com/configure/environment-configuration-settings.html#database", # Deploy redirects "deploy/mobile-apps-faq.html": @@ -2456,11 +2494,39 @@ def setup(_: Sphinx): "install/install-centos-oracle-scientific": "https://docs.mattermost.com/install/install-rhel-8.html", -"integrate/ms-teams-interoperability.html": - "https://docs.mattermost.com/integrate/microsoft-teams-interoperability.html", +"install/install-common-intro.html": + "https://docs.mattermost.com/install/install-tar.html", +"install/install-latest-tarball.html": + "https://docs.mattermost.com/install/install-tar.html", +"install/setup-mattermost-server.html": + "https://docs.mattermost.com/install/install-tar.html", +"install/common-prod-deploy-docker.html": + "https://docs.mattermost.com/install/install-docker.html", +"install/common-deploy-faq.html": + "https://docs.mattermost.com/install/install-tar.html", +"install/install-rhel-nginx.html": + "https://docs.mattermost.com/install/setup-nginx-proxy.html", +"install/config-ssl-http2-nginx.html": + "https://docs.mattermost.com/install/setup-nginx-proxy.html#configure-nginx-with-ssl-and-http-2", +"install/config-proxy-nginx.html": + "https://docs.mattermost.com/install/setup-nginx-proxy.html", +"install/install-nginx.html": + "https://docs.mattermost.com/install/setup-nginx-proxy.html", +"install/faq_kubernetes.html": + "https://docs.mattermost.com/install/install-kubernetes.html", +"install/common-prod-deploy-tar.html": + "https://docs.mattermost.com/install/install-tar.html", +"install/common-prod-deploy-omnibus.html": + "https://docs.mattermost.com/install/install-tar.html", +"install/common-local-deploy-docker.html": + "https://docs.mattermost.com/install/trial-mattermost-using-docker.html", +"install/config-mattermost-server.html": + "https://docs.mattermost.com/guides/get-started-with-administration.html", # Integrations redirects. # The integrations directory and its contents have been archived in FY23 Q2 and all applicable content has been moved from docs.mm.com to developers.mm.com. +"integrate/ms-teams-interoperability.html": + "https://docs.mattermost.com/integrate/microsoft-teams-interoperability.html", "integrations/cloud-incoming-webhooks.html": "https://developers.mattermost.com/integrate/admin-guide/", "integrations/cloud-outgoing-webhooks.html": @@ -2685,7 +2751,10 @@ def setup(_: Sphinx): "https://docs.mattermost.com/about/cloud-vpc-private-connectivity.html", "manage/workspace-usage.html": "https://docs.mattermost.com/guides/cloud-workspace-management.html", - +"manage/common-support-packet.html": + "https://docs.mattermost.com/manage/generating-support-packet.html", +"manage/bulk-export-data.html": + "https://docs.mattermost.com/manage/bulk-export-tool.html", # Messaging redirects "messaging/about-teams-channels-messages.html#teams": @@ -3152,6 +3221,20 @@ def setup(_: Sphinx): "https://docs.mattermost.com/onboard/delegated-granular-administration.html", "onboard/sso-office.html": "https://docs.mattermost.com/onboard/sso-entraid.html", +"onboard/guest-account-access.html": + "https://docs.mattermost.com/onboard/guest-accounts.html", +"onboard/sso-saml-before-you-begin.html": + "https://docs.mattermost.com/configure/authentication-configuration-settings.html#saml-2-0", +"onboard/common-sso-openidconnect.html": + "https://docs.mattermost.com/onboard/sso-openidconnect.html", +"onboard/common-disable-mfa.html": + "https://docs.mattermost.com/onboard/multi-factor-authentication.html", +"onboard/common-sso-google.html": + "https://docs.mattermost.com/onboard/sso-google.html", +"onboard/sso-saml-faq.html": + "https://docs.mattermost.com/onboard/sso-saml.html", +"onboard/common-sso-entraid.html": + "https://docs.mattermost.com/onboard/sso-entraid.html", # Overview redirects "overview/architecture.html": diff --git a/source/configure/calls-deployment.rst b/source/configure/calls-deployment.rst index cf5b186603b..44cbfeb6a10 100644 --- a/source/configure/calls-deployment.rst +++ b/source/configure/calls-deployment.rst @@ -228,7 +228,7 @@ Both the plugin and the external ``rtcd`` service expose some Prometheus metrics Calls plugin metrics ^^^^^^^^^^^^^^^^^^^^ -Metrics for the calls plugin are exposed through the ``/plugins/com.mattermost.calls/metrics`` subpath under the existing Mattermost server metrics endpoint. This is controlled by the :ref:`Listen address for performance ` configuration setting. It defaults to port ``8067``. +Metrics for the calls plugin are exposed through the ``/plugins/com.mattermost.calls/metrics`` subpath under the existing Mattermost server metrics endpoint. This is controlled by the :ref:`Listen address for performance ` configuration setting. It defaults to port ``8067``. .. note:: On Mattermost versions prior to v9.5, plugin metrics were exposed through the public ``/plugins/com.mattermost.calls/metrics`` API endpoint controlled by the :ref:`Web server listen address ` configuration setting. This defaults to port ``8065``. diff --git a/source/configure/common-config-settings-notation.rst b/source/configure/common-config-settings-notation.rst deleted file mode 100644 index 2c2e46ee17a..00000000000 --- a/source/configure/common-config-settings-notation.rst +++ /dev/null @@ -1,9 +0,0 @@ -:orphan: -:nosearch: - -.. 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``. \ No newline at end of file diff --git a/source/configure/database-configuration-settings.rst b/source/configure/database-configuration-settings.rst deleted file mode 100644 index b4b617d9d36..00000000000 --- a/source/configure/database-configuration-settings.rst +++ /dev/null @@ -1,609 +0,0 @@ -:orphan: -:nosearch: - -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. - -.. include:: ../_static/badges/academy-mattermost-database.rst - :start-after: :nosearch: - -.. config:setting:: database-drivername - :displayname: Driver name (Database) - :systemconsole: N/A - :configjson: .SqlSettings.DriverName - :environment: MM_SQLSETTINGS_DRIVERNAME - :description: The type of database. Either **postgres** or **mysql**. The default value is **mysql**. - -Driver name -~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| The type of database. Can be either: | - System Config path: N/A | -| | - ``config.json`` setting: ``".SqlSettings.DriverName",`` | -| - **mysql**: **(Default)** Enables driver to MySQL database. | - Environment variable: ``MM_SQLSETTINGS_DRIVERNAME`` | -| - **postgres**: Enables driver to PostgreSQL database. | | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ - -.. config:setting:: database-datasource - :displayname: Data source (Database) - :systemconsole: N/A - :configjson: .SqlSettings.DataSource - :environment: MM_SQLSETTINGS_DATASOURCE - :description: The connection string to the master database. - -Data source -~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| The connection string to the master database. | - System Config path: N/A | -| | - ``config.json`` setting: ``".SqlSettings.DataSource",`` | -| String input. | - Environment variable: ``MM_SQLSETTINGS_DATASOURCE`` | -| | | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| **PostgreSQL databases** | -| | -| When **Driver Name** is set to ``postgres``, use a connection string in the form of: | -| ``postgres://mmuser:password@hostname_or_IP:5432/mattermost_test?sslmode=disable&connect_timeout=10`` | -| | -| **To use TLS with PostgreSQL databases** | -| | -| The parameter to encrypt connection against a PostgreSQL server is ``sslmode``. The library used to interact with PostgreSQL server is | -| `pq `__. Currently, it's not possible to use all the values that you could pass to a standard | -| PostgreSQL Client ``psql "sslmode=value"`` See the `SSL Mode Descriptions `__ | -| documentation for details. | -| | -| Your database admin must configure the functionality according to the supported values described below: | -| | -| +----------------------------------------+-----------------+---------------------------------------------------------------------------+ | -| | Short description of the ``sslmode`` | Value | Example of a data source name | | -| | parameter | | | | -| +========================================+=================+===========================================================================+ | -| | Don't use TLS / SSL encryption against | ``disable`` | ``postgres://mmuser:password@hostname_or_IP:5432/mattermost_test | | -| | the PostgreSQL server. | | ?sslmode=disable&connect_timeout=10`` | | -| | | | | | -| | Default value in file ``config.json`` | | | | -| +----------------------------------------+-----------------+---------------------------------------------------------------------------+ | -| | The data is encrypted and the network | ``require`` | ``postgres://mmuser:password@hostname_or_IP:5432/mattermost_test | | -| | is trusted. | | ?sslmode=require&connect_timeout=10`` | | -| | | | | | -| | Default value is ``sslmode`` when | | | | -| | omitted. | | | | -| +----------------------------------------+-----------------+---------------------------------------------------------------------------+ | -| | The data is encrypted when connecting | ``verify-ca`` | ``postgres://mmuser:password@hostname_or_IP:5432/mattermost_test | | -| | to a trusted server. | | ?sslmode=verify-ca&connect_timeout=10`` | | -| +----------------------------------------+-----------------+---------------------------------------------------------------------------+ | -| | The data is encrypted when connecting | ``verify-full`` | ``postgres://mmuser:password@hostname_or_IP:5432/mattermost_test | | -| | to a trusted server. | | ?sslmode=verify-full&connect_timeout=10`` | | -| +----------------------------------------+-----------------+---------------------------------------------------------------------------+ | -| | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| **MySQL databases** | -| | -| When **Driver Name** is set to ``mysql``, we recommend using ``collation`` over using ``charset``. | -| | -| To specify collation: | -| | -| .. code-block:: text | -| | -| "SqlSettings": { | -| "DataSource": | -| "@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: | -| | -| .. code-block:: text | -| | -| "SqlSettings": { | -| "DataSource": "@tcp(hostname or IP:3306)/mattermost?charset=utf8mb4,utf8", | -| [...] | -| } | -| | -| **Note**: If you’re using MySQL 8.0 or later, the default collation has changed to ``utf8mb4_0900_ai_ci``. See our | -| :doc:`Database Software Requirements ` documentation for details on MySQL 8.0 support. | -| | -| **To use TLS with MySQL databases** | -| | -| The parameter to encrypt connection against a MySQL server is ``tls``. | -| The library used to interact with MySQL is `Go-MySQL-Driver `__. | -| For the moment, it's not possible to use all the values that you could pass to a standard MySQL Client ``mysql --ssl-mode=value``. | -| See `Connection-Encryption Option Summary `__ | -| documentation for a version 8.0 example. | -| | -| Your database admin must configure the functionality according to supported values described below: | -| | -| +----------------------------------------+-----------------+---------------------------------------------------------------------------+ | -| | Short description of the ``tls`` | Value | Example of a data source name | | -| | parameter | | | | -| +========================================+=================+===========================================================================+ | -| | Don't use TLS / SSL encryption against | ``false`` | ``"@tcp(hostname or IP:3306)/mattermost_test | | -| | MySQL server. | | ?charset=utf8mb4,utf8&writeTimeout=30s&tls=false"`` | | -| +----------------------------------------+-----------------+---------------------------------------------------------------------------+ | -| | Use TLS / SSL encryption against | ``true`` | ``"@tcp(hostname or IP:3306)/mattermost_test | | -| | MySQL server. | | ?charset=utf8mb4,utf8&writeTimeout=30s&tls=true"`` | | -| +----------------------------------------+-----------------+---------------------------------------------------------------------------+ | -| | Use TLS / SSL encryption with a self- | ``skip-verify`` | ``"@tcp(hostname or IP:3306)/mattermost_test | | -| | signed certificate against | | ?charset=utf8mb4,utf8&writeTimeout=30s&tls=skip-verify"`` | | -| | MySQL server. | | | | -| +----------------------------------------+-----------------+---------------------------------------------------------------------------+ | -| | Use TLS / SSL encryption if server | ``preferred`` | ``"@tcp(hostname or IP:3306)/mattermost_test | | -| | advertises a possible fallback; | | ?charset=utf8mb4,utf8&writeTimeout=30s&tls=preferred"`` | | -| | unencrypted if it's not advertised. | | | | -| +----------------------------------------+-----------------+---------------------------------------------------------------------------+ | -| | -+------------------------------------------------------------+-----------------------------------------------------------------------------+ -| **AWS High Availablity RDS cluster deployments** | -| | -| For an AWS High Availability RDS cluster deployment, point this configuration setting to the write/read endpoint at the **cluster** | -| level to benefit from the AWS failover handling. AWS takes care of promoting different database nodes to be the writer node. | -| Mattermost doesn't need to manage this. See the | -| :ref:`high availablility database configuration ` documentation | -| for details. | -+------------------------------------------------------------+-----------------------------------------------------------------------------+ - -.. config:setting:: database-maxopenconnections - :displayname: Maximum open connections (Database) - :systemconsole: Environment > Database - :configjson: .SqlSettings.MaxOpenConns - :environment: MM_SQLSETTINGS_MAXOPENCONNS - :description: The maximum number of idle connections held open to the database. Default is **300**. - -Maximum open connections -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+--------------------------------------------------------+------------------------------------------------------------------+ -| The maximum number of open connections to the | - System Config path: **Environment > Database** | -| database. | - ``config.json`` setting: ``".SqlSettings.MaxOpenConns": 300,`` | -| | - Environment variable: ``MM_SQLSETTINGS_MAXOPENCONNS`` | -| Numerical input. Default is **300** for self-hosted | | -| deployments, and **100** for Cloud deployments. | | -+--------------------------------------------------------+------------------------------------------------------------------+ - -.. config:setting:: database-querytimeout - :displayname: Query timeout (Database) - :systemconsole: Environment > Database - :configjson: .SqlSettings.QueryTimeout - :environment: MM_SQLSETTINGS_QUERYTIMEOUT - :description: The amount of time to wait, in seconds, for a response from the database after opening a connection and sending the query. Default is **30** seconds. - -Query timeout -~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+--------------------------------------------------------+------------------------------------------------------------------+ -| The amount of time to wait, in seconds, for a response | - System Config path: **Environment > Database** | -| from the database after opening a connection and | - ``config.json`` setting: ``".SqlSettings.QueryTimeout: 30",`` | -| sending the query. | - Environment variable: ``MM_SQLSETTINGS_QUERYTIMEOUT`` | -| | | -| Numerical input in seconds. Default is **30** seconds. | | -+--------------------------------------------------------+------------------------------------------------------------------+ - -.. config:setting:: database-maxconnectionlifetime - :displayname: Maximum connection lifetime (Database) - :systemconsole: Environment > Database - :configjson: .SqlSettings.ConnMaxLifetimeMilliseconds - :environment: MM_SQLSETTINGS_CONNMAXLIFETIMEMILLISECONDS - :description: Maximum lifetime for a connection to the database, in milliseconds. Default is **3600000** milliseconds (1 hour). - -Maximum connection lifetime -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+--------------------------------------------------------+-------------------------------------------------------------------------------------+ -| Maximum lifetime for a connection to the database, | - System Config path: **Environment > Database** | -| in milliseconds. Use this setting to configure the | - ``config.json`` setting: ``".SqlSettings.ConnMaxLifetimeMilliseconds: 3600000",`` | -| maximum amount of time a connection to the database | - Environment variable: ``MM_SQLSETTINGS_CONNMAXLIFETIMEMILLISECONDS`` | -| may be reused | | -| | | -| Numerical input in milliseconds. Default is | | -| **3600000** milliseconds (1 hour). | | -+--------------------------------------------------------+-------------------------------------------------------------------------------------+ - -.. config:setting:: database-connmaxidletime - :displayname: Maximum connection idle timeout (Database) - :systemconsole: Environment > Database - :configjson: .SqlSettings.ConnMaxIdleTimeMilliseconds - :environment: MM_SQLSETTINGS_CONNMAXIDLETIMEMILLISECONDS - :description: Maximum time a database connection can remain idle, in milliseconds. Default is **300000** milliseconds (5 minutes). - -Maximum connection idle timeout -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+--------------------------------------------------------+-------------------------------------------------------------------------------------+ -| Maximum time a database connection can remain idle, | - System Config path: **Environment > Database** | -| in milliseconds. | - ``config.json`` setting: ``".SqlSettings.ConnMaxIdleTimeMilliseconds: 300000",`` | -| | - Environment variable: ``MM_SQLSETTINGS_CONNMAXIDLETIMEMILLISECONDS`` | -| Numerical input in milliseconds. Default is **300000** | | -| (5 minutes). | | -+--------------------------------------------------------+-------------------------------------------------------------------------------------+ - -.. config:setting:: database-minhashtaglength - :displayname: Minimum hashtag length (Database) - :systemconsole: Environment > Database - :configjson: .SqlSettings.MinimumHashtagLength - :environment: MM_SQLSETTINGS_MINIMUMHASHTAGLENGTH - :description: Minimum number of characters in a hashtag. This value must be greater than or equal to **2**. Default is **3**. - -Minimum hashtag length -~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+----------------------------------------------------------------------+-------------------------------------------------------------------------+ -| Minimum number of characters in a hashtag. | - System Config path: **Environment > Database** | -| This value must be greater than or equal to **2**. | - ``config.json`` setting: ``".SqlSettings.MinimumHashtagLength: 3",`` | -| | - Environment variable: ``MM_SQLSETTINGS_MINIMUMHASHTAGLENGTH`` | -+----------------------------------------------------------------------+-------------------------------------------------------------------------+ -| **Note**: MySQL databases must be configured to support searching strings shorter than three characters. See the | -| `MySQL documentation `__ for details. | -+----------------------------------------------------------------------+-------------------------------------------------------------------------+ - -.. config:setting:: database-sqltrace - :displayname: SQL statement logging (Database) - :systemconsole: Environment > Database - :configjson: .SqlSettings.Trace - :environment: MM_SQLSETTINGS_TRACE - - - **true**: Executing SQL statements are written to the log. - - **false**: **(Default)** SQL statements aren't written to the log. - -SQL statement logging -~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| Executed SQL statements can be written to the log for | - System Config path: **Environment > Database** | -| development. | - ``config.json`` setting: ``".SqlSettings.Trace: false",`` | -| | - Environment variable: ``MM_SQLSETTINGS_TRACE`` | -| - **true**: Executing SQL statements are written to the log. | | -| - **false**: **(Default)** SQL statements aren't written | | -| to the log. | | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ - -Recycle database connections -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: ../_static/badges/ent-only.rst - :start-after: :nosearch: - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E20

- -+--------------------------------------------------------+------------------------------------------------------------------+ -| Select the **Recycle Database Connections** button to | - System Config path: **Environment > Database** | -| manually recycle the connection pool by closing the | - ``config.json`` setting: N/A | -| current set of open connections to the database | - Environment variable: N/A | -| within 20 seconds, and then creating a new set of | | -| connections. | | -| | | -| To fail over without stopping the server, change the | | -| database line in the ``config.json`` file, select | | -| **Reload Configuration from Disk** via **Environment | | -| > Web Server**, then select **Recycle Database | | -| Connections**. | | -+--------------------------------------------------------+------------------------------------------------------------------+ - -.. config:setting:: database-disablesearch - :displayname: Disable database search (Database) - :systemconsole: Environment > Database - :configjson: .SqlSettings.DisableDatabaseSearch - :environment: MM_SQLSETTINGS_DISABLEDATABASESEARCH - - - **true**: Disables the use of the database to perform searches. If another search engine isn't configured, setting this value to ``true`` will result in empty search results. - - **false**: **(Default)** Database search isn't disabled. - -Disable database search -~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+------------------------------------------------------------------------------+ -| When other search engines are configured, such as | - System Config path: **Environment > Database** | -| :doc:`Elasticsearch `, | - ``config.json`` setting: ``".SqlSettings.DisableDatabaseSearch: false",`` | -| the database can be disabled to perform searches. | - Environment variable: ``MM_SQLSETTINGS_DISABLEDATABASESEARCH`` | -| | | -| - **true**: Disables the use of the database to perform | | -| searches. If another search engine isn't configured, | | -| setting this value to ``true`` will result in empty search | | -| results. | | -| - **false**: **(Default)** Database search isn't disabled. | | -+---------------------------------------------------------------+------------------------------------------------------------------------------+ -| Search behavior in Mattermost depends on which search engines are enabled. | -| | -| - When :doc:`Elasticsearch ` is enabled, Mattermost will try to use it first. | -| - If Elasticsearch fails or is disabled, Mattermost will attempt to use :doc:`Bleve `, if enabled. If this occurs, | -| you will see the warning ``Encountered error on SearchPostsInTeamForUser.`` | -| - If both Elasticsearch and Bleve fail or are disabled, Mattermost tries to search the database directly, if this is enabled. | -| - If all of the above methods fail or are disabled, the search results will be empty. | -+---------------------------------------------------------------+------------------------------------------------------------------------------+ - -Applied schema migrations -~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -A list of all migrations that have been applied to the data store based on the version information available in the ``db_migrations`` table. Select **About Mattermost** from the product menu to review the current database schema version applied to your deployment. - - -.. config:setting:: database-activesearchbackend - :displayname: Active search backend (Database) - :systemconsole: Environment > Database - :configjson: N/A - :environment: N/A - :description: Read-only display of the currently active backend used for search. - -Active Search Backend -~~~~~~~~~~~~~~~~~~~~~ - -Read-only display of the currently active backend used for search. Values can include ``none``, ``database``, ``elasticsearch``, or ``bleve``. - -.. config:setting:: database-readreplicas - :displayname: Read replicas (Database) - :systemconsole: N/A - :configjson: .SqlSettings.DataSourceReplicas - :environment: MM_SQLSETTINGS_DATASOURCEREPLICAS - :description: Specifies the connection strings for the read replica databases. - -Read replicas -~~~~~~~~~~~~~ - -.. include:: ../_static/badges/ent-pro-only.rst - :start-after: :nosearch: - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+--------------------------------------------------------+-----------------------------------------------------------------------+ -| Specifies the connection strings for the read replica | - System Config path: N/A | -| databases. | - ``config.json`` setting: ``".SqlSettings.DataSourceReplicas": []`` | -| | - Environment variable: ``MM_SQLSETTINGS_DATASOURCEREPLICAS`` | -+--------------------------------------------------------+-----------------------------------------------------------------------+ -| **Note**: Each database connection string in the array must be in the same form used for the | -| `Data source <#data-source>`__ setting. | -+--------------------------------------------------------+-----------------------------------------------------------------------+ -| **AWS High Availablity RDS cluster deployments** | -| | -| For an AWS High Availability RDS cluster deployment, point this configuration setting directly to the underlying read-only | -| node endpoint within the RDS cluster to circumvent the failover/load balancing that AWS/RDS takes care of (except for the | -| write traffic). Mattermost has its own method of balancing the read-only connections, and can also balance those queries to | -| the data source/write+read connection should those nodes fail. See the | -| :ref:`high availablility database configuration ` | -| documentation for details. | -+--------------------------------------------------------+-----------------------------------------------------------------------+ - -.. config:setting:: database-searchreplicas - :displayname: Search replicas (Database) - :systemconsole: N/A - :configjson: .SqlSettings.DataSourceSearchReplicas - :environment: MM_SQLSETTINGS_DATASOURCESEARCHREPLICAS - - Specifies the connection strings for the search replica databases. - A search replica is similar to a read replica, but is used only for handling search queries. - -Search replicas -~~~~~~~~~~~~~~~ - -.. include:: ../_static/badges/ent-pro-only.rst - :start-after: :nosearch: - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+--------------------------------------------------------+-----------------------------------------------------------------------------+ -| Specifies the connection strings for the search | - System Config path: N/A | -| replica databases. A search replica is similar to a | - ``config.json`` setting: ``".SqlSettings.DataSourceSearchReplicas": []`` | -| read replica, but is used only for handling search | - Environment variable: ``MM_SQLSETTINGS_DATASOURCESEARCHREPLICAS`` | -| queries. | | -+--------------------------------------------------------+-----------------------------------------------------------------------------+ -| **Note**: Each database connection string in the array must be in the same form used for the `Data source <#data-source>`__ | -| setting. | -+--------------------------------------------------------+-----------------------------------------------------------------------------+ -| **AWS High Availablity RDS cluster deployments** | -| | -| For an AWS High Availability RDS cluster deployment, point this configuration setting directly to the underlying read-only | -| node endpoint within the RDS cluster to circumvent the failover/load balancing that AWS/RDS takes care of (except for the | -| write traffic). Mattermost has its own method of balancing the read-only connections, and can also balance those queries to | -| the data source/write+read connection should those nodes fail. See the | -| :ref:`high availablility database configuration ` | -| documentation for details. | -+--------------------------------------------------------+-----------------------------------------------------------------------------+ - -.. config:setting:: database-replicalagsettings - :displayname: Replica lag settings (Database) - :systemconsole: N/A - :configjson: .SqlSettings.ReplicaLagSettings - :environment: MM_SQLSETTINGS_REPLICALAGSETTINGS - :description: Specifies a connection string and user-defined SQL queries on the database to measure replica lag for a single replica instance. - -Replica lag settings -~~~~~~~~~~~~~~~~~~~~ - -.. include:: ../_static/badges/ent-only.rst - :start-after: :nosearch: - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E20

- -+--------------------------------------------------------+----------------------------------------------------------------------------------+ -| String array input specifies a connection string and | - System Config path: N/A | -| user-defined SQL queries on the database to measure | - ``config.json`` setting: ``".SqlSettings.ReplicaLagSettings": []`` | -| replica lag for a single replica instance. | - Environment variable: ``MM_SQLSETTINGS_REPLICALAGSETTINGS`` | -| | | -| These settings monitor absolute lag based on binlog | | -| distance/transaction queue length, and the time taken | | -| for the replica to catch up. | | -| | | -| String array input consists of: | | -| | | -| - ``DataSource``: The database credentials to connect | | -| to the database instance. | | -| - ``QueryAbsoluteLag``: A plain SQL query that must | | -| return a single row. The first column must be the | | -| node value of the Prometheus metric, and the second | | -| column must be the value of the lag used to | | -| measure absolute lag. | | -| - ``QueryTimeLag``: A plain SQL query that must | | -| return a single row. The first column must be the | | -| node value of the Prometheus metric, and the second | | -| column must be the value of the lag used to measure | | -| the time lag. | | -+--------------------------------------------------------+----------------------------------------------------------------------------------+ -| **Notes**: | -| | -| - The ``QueryAbsoluteLag`` and ``QueryTimeLag`` queries must return a single row. | -| - To properly monitor this, you must setup :doc:`performance monitoring ` | -| for Mattermost. | -+--------------------------------------------------------+----------------------------------------------------------------------------------+ - -1. Configure the replica lag metric based on your database type. See the following tabs for details on configuring this for each database type. - - .. tab:: AWS Aurora - - Add the configuration highlighted below to your ``SqlSettings.ReplicaLagSettings`` array. You only need to add this once because replication statistics for AWS Aurora nodes are visible across all server instances that are members of the cluster. Be sure to change the ``DataSource`` to point to a single node in the group. - - For more information on Aurora replication stats, see the `AWS Aurora documentaion `__. - - **Example:** - - .. code-block:: json - :emphasize-lines: 4,5,6,7,8 - - { - "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=<>" - } - ] - } - } - - .. tab:: MySQL Group Replication - - Add the configuration highlighted below to your ``SqlSettings.ReplicaLagSettings`` array. You only need to add this once because replication statistics for all nodes are shared across all server instances that are members of the MySQL replication group. Be sure to change the ``DataSource`` to point to a single node in the group. - - For more information on group replication stats, see the `MySQL documentation `__. - - **Example:** - - .. code-block:: json - :emphasize-lines: 4,5,6,7,8 - - { - "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": "" - } - ] - } - } - - .. tab:: PostgreSQL replication slots - - 1. Add the configuration highlighted below to your ``SqlSettings.ReplicaLagSettings`` array. This query should run against the **primary** node in your cluster, to do this change the ``DataSource`` to match the `SqlSettings.DataSource <#data-source>`__ setting you have configured. - - For more information on pg_stat_replication, see the `PostgreSQL documentation `__. - - **Example:** - - .. code-block:: json - :emphasize-lines: 4,5,6,7,8 - - { - "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": "" - } - ] - } - } - - 2. Grant permissions to the database user for ``pg_monitor``. This user should be the same user configured above in the ``DataSource`` string. - - For more information on roles, see the `PostgreSQL documentation `__. - - .. code-block:: sh - - sudo -u postgres psql - postgres=# GRANT pg_monitor TO mmuser; - -2. Save the config and restart all Mattermost nodes. -3. Navigate to your Grafana instance monitoring Mattermost and open the `Mattermost Performance Monitoring v2 `__ dashboard. -4. The ``QueryTimeLag`` chart is already setup for you utilizing the existing ``Replica Lag`` chart. If using ``QueryAbsoluteLag`` metric clone the ``Replica Lag`` chart and edit the query to use the below absolute lag metrics and modify the title to be ``Replica Lag Absolute``. - - .. code-block:: text - - mattermost_db_replica_lag_abs{instance=~"$server"} - - .. image:: ../../source/images/database-configuration-settings-replica-lag-grafana-1.jpg - :alt: A screenshot showing how to clone a chart within Grafana - - - .. image:: ../../source/images/database-configuration-settings-replica-lag-grafana-2.jpg - :alt: A screenshot showing the specific edits to make to the cloned grafana chart. - - -.. config:setting:: database-replicamonitorintervalseconds - :displayname: Replica monitor interval (Database) - :systemconsole: N/A - :configjson: .SqlSettings.ReplicaMonitorIntervalSeconds - :environment: MM_SQLSETTINGS_REPLICAMONITORINTERVALSECONDS - - Specifies how frequently unhealthy replicas will be monitored for liveness check. Mattermost will dynamically choose a replica if it's alive. - -Replica monitor interval (seconds) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: ../_static/badges/allplans-selfhosted.rst - :start-after: :nosearch: - -+--------------------------------------------------------+---------------------------------------------------------------------------------+ -| Specifies how frequently unhealthy replicas will be | - System Config path: N/A | -| monitored for liveness check. Mattermost will | - ``config.json`` setting: ``".SqlSettings.ReplicaMonitorIntervalSeconds": 5`` | -| dynamically choose a replica if it's alive. | - Environment variable: ``MM_SQLSETTINGS_REPLICAMONITORINTERVALSECONDS`` | -| | | -| Numerical input. Default is 5 seconds. | | -+--------------------------------------------------------+---------------------------------------------------------------------------------+ diff --git a/source/configure/developer-mode-configuration-settings.rst b/source/configure/developer-mode-configuration-settings.rst deleted file mode 100644 index 67e51602e5d..00000000000 --- a/source/configure/developer-mode-configuration-settings.rst +++ /dev/null @@ -1,150 +0,0 @@ -:orphan: -:nosearch: - -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. - -.. config:setting:: dev-enabletesting - :displayname: Enable testing commands (Developer) - :systemconsole: Environment > Developer - :configjson: .ServiceSettings.EnableTesting - :environment: MM_SERVICESETTINGS_ENABLETESTING - :description: Enable or disable the ``/test`` slash command. - - - **true**: **(Default)** The ``/test`` slash command is enabled to load test accounts and test data. - - **false**: The ``/test`` slash command is disabled. - -Enable testing commands -~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------+--------------------------------------------------------------------------+ -| Enable or disable the ``/test`` slash command. | - System Config path: **Environment > Developer** | -| | - ``config.json setting``: ``".ServiceSettings.EnableTesting": true",`` | -| - **true**: **(Default)** The ``/test`` slash | - Environment variable: ``MM_SERVICESETTINGS_ENABLETESTING`` | -| command is enabled to load test accounts | | -| and test data. | | -| - **false**: The ``/test`` slash command is | | -| disabled. | | -+---------------------------------------------------+--------------------------------------------------------------------------+ - -.. config:setting:: dev-enabledeveloper - :displayname: Enable developer mode (Developer) - :systemconsole: Environment > Developer - :configjson: .ServiceSettings.EnableDeveloper - :environment: MM_SERVICESETTINGS_ENABLEDEVELOPER - :description: Enable or disable developer mode. - - - **true**: **(Default)** Javascript errors are shown in a banner at the top of Mattermost the user interface. Not recommended for use in production. - - **false**: Users are not alerted to Javascript errors. - -Enable developer mode -~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+-----------------------------------------------+---------------------------------------------------------------------------+ -| Enable or disable developer mode. | - System Config path: **Environment > Developer** | -| | - ``config.json setting``: ``".ServiceSettings.EnableDeveloper": true",`` | -| - **true**: **(Default)** Javascript errors | - Environment variable: ``MM_SERVICESETTINGS_ENABLEDEVELOPER`` | -| are shown in a banner at the top of | | -| Mattermost the user interface. | | -| Not recommended for use in production. | | -| - **false**: Users are not alerted to | | -| Javascript errors. | | -+-----------------------------------------------+---------------------------------------------------------------------------+ - -.. config:setting:: dev-enableclientdebugging - :displayname: Enable client debugging (Developer) - :systemconsole: Environment > Developer - :configjson: .ServiceSettings.EnableClientPerformanceDebugging - :environment: MM_SERVICESETTINGS_ENABLECLIENTPERFORMANCEDEBUGGING - :description: Enable or disable client-side debugging settings found in *Settings > Advanced > Debugging* for individual users. - - - **true**: Those settings are visible and can be enabled by users. - - **false**: **(Default)** Those settings are hidden and disabled. - -Enable client debugging -~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------+---------------------------------------------------------------------------------------------+ -| Enable or disable client-side debugging settings | - System Config path: **Environment > Developer** | -| found in **Settings > Advanced > Debugging** | - ``config.json setting``: ``".ServiceSettings.EnableClientPerformanceDebugging": false",`` | -| for individual users. | - Environment variable: ``MM_SERVICESETTINGS_ENABLECLIENTPERFORMANCEDEBUGGING`` | -| | | -| - **true**: Those settings are visible and can | | -| be enabled by users. | | -| - **false**: **(Default)** Those settings are | | -| hidden and disabled. | | -+---------------------------------------------------+---------------------------------------------------------------------------------------------+ -| See the :ref:`client debugging ` documentation to learn more. | -+---------------------------------------------------+---------------------------------------------------------------------------------------------+ - -.. config:setting:: dev-allowuntrustedinternalconnections - :displayname: Allow untrusted internal connections (Developer) - :systemconsole: Environment > Developer - :configjson: .ServiceSettings.AllowedUntrustedInternalConnections - :environment: MM_SERVICESETTINGS_ALLOWUNTRUSTEDINTERNALCONNECTIONS - :description: This setting is a whitelist of local network addresses that can be requested by the Mattermost server. - -Allow untrusted internal connections -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+-----------------------------------------------+-----------------------------------------------------------------------------------------------+ -| Limit the ability for the Mattermost server | - System Config path: **Environment > Developer** | -| to make untrusted requests within its local | - ``config.json setting``: ``".ServiceSettings.AllowedUntrustedInternalConnections": "",`` | -| network. A request is considered “untrusted” | - Environment variable: ``MM_SERVICESETTINGS_ALLOWEDUNTRUSTEDINTERNALCONNECTIONS`` | -| when it’s made on behalf of a client. | | -+-----------------------------------------------+-----------------------------------------------------------------------------------------------+ -| This setting is a whitelist of local network addresses that can be requested by the Mattermost server. It’s configured as a | -| whitespace-separated list of hostnames, IP addresses, and CIDR ranges that can be accessed. | -| | -| Requests that can only be configured by system admins are considered trusted and won't be affected by this setting. Trusted URLs include | -| ones used for OAuth login or for sending push notifications. | -| | -| The following features make untrusted requests and are affected by this setting: | -| | -| - Integrations using webhooks, slash commands, or message actions. This prevents them from requesting endpoints within the local network. | -| - Link previews. When a link to a local network address is posted in a chat message, this prevents a link preview from being displayed. | -| - The local :doc:`image proxy `. If the local image proxy is enabled, images located on | -| the local network cannot be used by integrations or posted in chat messages. | -+-----------------------------------------------+-----------------------------------------------------------------------------------------------+ -| | -| Some examples of when you may want to modify this setting include: | -| | -| - When installing a plugin that includes its own images, such as `Matterpoll `__, you'll need to | -| add the Mattermost server’s domain name to | -| this list. | -| - When running a bot or webhook-based integration on your local network, you’ll need to add the hostname of the bot/integration to this list. | -| - If your network is configured in such a way that publicly-accessible web pages or images are accessed by the Mattermost server using | -| their internal IP address, the hostnames for those servers must be added to this list. | -+-----------------------------------------------+-----------------------------------------------------------------------------------------------+ -| **Warning**: This setting is intended to prevent users located outside your local network from using the Mattermost server to request | -| confidential data from inside your network. Care should be used when configuring this setting to prevent unintended access to your local | -| network. | -+-----------------------------------------------+-----------------------------------------------------------------------------------------------+ -| **Notes**: | -| | -| - The public IP of the Mattermost application server itself is also considered a reserved IP. | -| - Use whitespaces instead of commas to list the hostnames, IP addresses, or CIDR ranges. | -| For example: ``webhooks.internal.example.com``, ``127.0.0.1``, or ``10.0.16.0/28``. | -| - IP address and domain name rules are applied before host resolution. | -| - CIDR rules are applied after host resolution, and only CIDR rules require DNS resolution. | -| - Mattermost attempts to match IP addresses and hostnames without even resolving. If that fails, Mattermost resolve using the local resolver | -| (by reading the ``/etc/hosts`` file first), then checking for matching CIDR rules. | -| For example, if the domain “webhooks.internal.example.com” resolves to the IP address ``10.0.16.20``, a webhook with the URL | -| ``https://webhooks.internal.example.com/webhook`` can be whitelisted using ``webhooks.internal.example.com``, or ``10.0.16.16/28``, | -| but not ``10.0.16.20``. | -+-----------------------------------------------+-----------------------------------------------------------------------------------------------+ diff --git a/source/configure/elasticsearch-configuration-settings.rst b/source/configure/elasticsearch-configuration-settings.rst deleted file mode 100644 index 1ce30ac64e2..00000000000 --- a/source/configure/elasticsearch-configuration-settings.rst +++ /dev/null @@ -1,770 +0,0 @@ -:orphan: -:nosearch: - -Elasticsearch provides enterprise-scale deployments with optimized search performance and prevents performance degradation and timeouts. Learn more about :doc:`Elasticsearch ` in our product documentation. - -You can configure the Elasticsearch environment in which Mattermost is deployed in **System Console > Environment > Elasticsearch**. You can also edit the ``config.json`` file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect. - -.. config:setting:: elastic-enableindexing - :displayname: Enable Elasticsearch indexing (Elasticsearch) - :systemconsole: Environment > Elasticsearch - :configjson: .Elasticsearchsettings.EnableIndexing - :environment: MM_ELASTICSEARCHSETTINGS_ENABLEINDEXING - :description: Configure Mattermost to index new posts automatically. - - - **true**: Indexing of new posts occurs automatically. - - **false**: **(Default)** Elasticsearch indexing is disabled and new messages aren't indexed. - -Enable Elasticsearch indexing -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+--------------------------------------------------------------------------------+ -| Configure Mattermost to index new posts automatically. | - System Config path: **Environment > Elasticsearch** | -| | - ``config.json`` setting: ``".Elasticsearchsettings.EnableIndexing: false",`` | -| - **true**: Indexing of new messages occurs automatically. | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_ENABLEINDEXING`` | -| - **false**: **(Default)** Elasticsearch indexing is disabled | | -| and new messages aren't indexed. | | -+---------------------------------------------------------------+--------------------------------------------------------------------------------+ -| **Notes**: | -| | -| - Core search happens in a relational database and is intended for deployments under about 2-3 million posts and file entries. Beyond that | -| scale, `enabling Elasticsearch for search queries <#enable-elasticsearch-for-search-queries>`__ is highly recommended | -| - If you anticipate your Mattermost server reaching more than 2.5 million posts and file entries, we recommend enabling Elasticsearch for | -| optimum search performance **before** reaching 3 million posts. | -| - For deployments with over 3 million posts, Elasticsearch is required to avoid significant performance issues, such as timeouts, with | -| :doc:`message searches ` and :doc:`@mentions `. | -| - If indexing is disabled and then re-enabled after an index is created, purge and rebuild the index to ensure complete search results. | -+---------------------------------------------------------------+--------------------------------------------------------------------------------+ - -.. config:setting:: elastic-backendtype - :displayname: Elasticsearch backend type (Elasticsearch) - :systemconsole: Environment > Elasticsearch - :configjson: .Elasticsearchsettings.Backend - :environment: MM_ELASTICSEARCHSETTINGS_BACKEND - :description: Set the type of search backend as either Elasticsearch or Opensearch. - -Backend type -~~~~~~~~~~~~~ - -+----------------------------------------------------+-----------------------------------------------------------------------------------+ -| The type of search backend. | - System Config path: **Environment > Elasticsearch** | -| | - ``config.json`` setting: ``".Elasticsearchsettings.Backend: elasticsearch",`` | -| - ``elasticsearch`` - (**Default**) | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_BACKEND`` | -| - ``opensearch`` - Required for AWS Opensearch | | -| customers. | | -+----------------------------------------------------+-----------------------------------------------------------------------------------+ - -.. important:: - - Mattermost v9.11 introduces support for `Elasticsearch v8 `__ and beta support for `Opensearch v1.x and v2.x `_. - - - Mattermost supports Elasticsearch v7.17+. However, we recommend upgrading your Elasticsearch v7 instance to v8.x. See the `Elasticsearch upgrade `_ documentation for details. - - Customers using Elasticsearch v8 must set ``action.destructive_requires_name`` to ``false`` in ``elasticsearch.yml`` to enable wildcard operations. - - **AWS Elasticsearch Customers** - - The official AWS Elasticsearch v8 client only works from Elasticsearch v7.11 and later. This is a breaking change for customers using AWS Elasticsearch v7.10.x. If you're using AWS Elasticsearch, you must upgrade to `AWS Opensearch `_. See the `AWS Amazon Opensearch upgrade `_ documentation for details. - - If you're using AWS Elasticsearch, you must: - - 1. Upgrade to AWS Opensearch for future compatibility. Refer to the `Opensearch upgrade `_ documentation for details. - 2. Disable "compatibility mode" in Opensearch. - 3. Upgrade the Mattermost server. - 4. Change the default ``ElasticsearchSettings.Backend`` configuration value from ``elasticsearch`` to ``opensearch`` using :ref:`mmctl config set `, or by editing the ``config.json`` file manually. This value cannot be changed using the System Console. See the Mattermost :ref:`Elasticsearch backend type ` documentation for additional details. - 5. Restart the Mattermost server. - -.. config:setting:: elastic-serverconnectionaddress - :displayname: Server connection address (Elasticsearch) - :systemconsole: Environment > Elasticsearch - :configjson: .Elasticsearchsettings.ConnectionUrl - :environment: MM_ELASTICSEARCHSETTINGS_CONNECTIONURL - :description: The address of the Elasticsearch server. - -Server connection address -~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+----------------------------------------------------+--------------------------------------------------------------------------+ -| The address of the Elasticsearch server. | - System Config path: **Environment > Elasticsearch** | -| | - ``config.json`` setting: ``".Elasticsearchsettings.ConnectionUrl",`` | -| | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_CONNECTIONURL`` | -+----------------------------------------------------+--------------------------------------------------------------------------+ - -.. config:setting:: elastic-CApath - :displayname: CA path (Elasticsearch) - :systemconsole: Environment > Elasticsearch - :configjson: .Elasticsearchsettings.CA - :environment: MM_ELASTICSEARCHSETTINGS_CA - :description: Optional path to the Custom Certificate Authority certificates for the Elasticsearch server. - -CA path -~~~~~~~ - -+----------------------------------------------------+--------------------------------------------------------------------------+ -| Optional path to the Custom Certificate Authority | - System Config path: **Environment > Elasticsearch** | -| certificates for the Elasticsearch server. | - ``config.json`` setting: ``".Elasticsearchsettings.CA",`` | -| | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_CA`` | -+----------------------------------------------------+--------------------------------------------------------------------------+ -| **Note**: Available from Mattermost v7.8. Can be used in conjunction with basic auth credentials or to replace them. | -| Leave this setting blank to use the default Certificate Authority certificates for the operating system. | -+----------------------------------------------------+--------------------------------------------------------------------------+ - -.. config:setting:: elastic-clientcertificatepath - :displayname: Client certificate path (Elasticsearch) - :systemconsole: Environment > Elasticsearch - :configjson: .Elasticsearchsettings.ClientCert - :environment: MM_ELASTICSEARCHSETTINGS_CLIENTCERT - :description: Optional client certificate for the connection to the Elasticsearch server in PEM format. - -Client certificate path -~~~~~~~~~~~~~~~~~~~~~~~ - -+----------------------------------------------------+--------------------------------------------------------------------------+ -| Optional client certificate for the connection to | - System Config path: **Environment > Elasticsearch** | -| the Elasticsearch server in the PEM format. | - ``config.json`` setting: ``".Elasticsearchsettings.ClientCert",`` | -| | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_CLIENTCERT`` | -+----------------------------------------------------+--------------------------------------------------------------------------+ -| **Note**: Available from Mattermost v7.8. Can be used in conjunction with basic auth credentials or to replace them. | -+----------------------------------------------------+--------------------------------------------------------------------------+ - -.. config:setting:: elastic-clientcertificatekeypath - :displayname: Client certificate key path (Elasticsearch) - :systemconsole: Environment > Elasticsearch - :configjson: .Elasticsearchsettings.ClientKey - :environment: MM_ELASTICSEARCHSETTINGS_CLIENTKEY - :description: Optional key for the client certificate in PEM format. - -Client certificate key path -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -+----------------------------------------------------+--------------------------------------------------------------------------+ -| Optional key for the client certificate in the PEM | - System Config path: **Environment > Elasticsearch** | -| format. | - ``config.json`` setting: ``".Elasticsearchsettings.ClientKey",`` | -| | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_CLIENTKEY`` | -+----------------------------------------------------+--------------------------------------------------------------------------+ -| **Note**: Available from Mattermost v7.8. Can be used in conjunction with basic auth credentials or to replace them. | -+----------------------------------------------------+--------------------------------------------------------------------------+ - -.. config:setting:: elastic-skiptlsverification - :displayname: Skip TLS verification (Elasticsearch) - :systemconsole: Environment > Elasticsearch - :configjson: .Elasticsearchsettings.SkipTLSVerification - :environment: MM_ELASTICSEARCHSETTINGS_SKIPTLSVERIFICATION - :description: The certificate step for TLS connections can be skipped. - - - **true**: Skips the certificate verification step for TLS connections. - - **false**: **(Default)** Mattermost does not skip certificate verification. - -Skip TLS verification -~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| The certificate step for TLS connections can be skipped. | - System Config path: **Environment > Elasticsearch** | -| | - ``config.json`` setting: ``".Elasticsearchsettings.SkipTLSVerification: false",`` | -| - **true**: Skips the certificate verification step for | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_SKIPTLSVERIFICATION`` | -| TLS connections. | | -| - **false**: **(Default)** Mattermost does not skip | | -| certificate verification. | | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ - -.. config:setting:: elastic-serverusername - :displayname: Server username (Elasticsearch) - :systemconsole: Environment > Elasticsearch - :configjson: .Elasticsearchsettings.UserName - :environment: MM_ELASTICSEARCHSETTINGS_USERNAME - :description: (Optional) The username to authenticate to the Elasticsearch server. - -Server username -~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| (Optional) The username to authenticate to the | - System Config path: **Environment > Elasticsearch** | -| Elasticsearch server. | - ``config.json`` setting: ``".Elasticsearchsettings.UserName",`` | -| | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_USERNAME`` | -| String input. | | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ - -.. config:setting:: elastic-serverpassword - :displayname: Server password (Elasticsearch) - :systemconsole: Environment > Elasticsearch - :configjson: .Elasticsearchsettings.Password - :environment: MM_ELASTICSEARCHSETTINGS_PASSWORD - :description: (Optional) The password to authenticate to the Elasticsearch server. - -Server password -~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| (Optional) The password to authenticate to the | - System Config path: **Environment > Elasticsearch** | -| Elasticsearch server. | - ``config.json`` setting: ``".Elasticsearchsettings.Password",`` | -| | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_PASSWORD`` | -| String input. | | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ - -.. config:setting:: elastic-enablesniffing - :displayname: Enable cluster sniffing (Elasticsearch) - :systemconsole: Environment > Elasticsearch - :configjson: .Elasticsearchsettings.Sniff - :environment: MM_ELASTICSEARCHSETTINGS_SNIFF - :description: Configure Mattermost to automatically find and connect to all data nodes in a cluster. - - - **true**: Sniffing finds and connects to all data nodes in your cluster automatically. - - **false**: **(Default)** Cluster sniffing is disabled. - -Enable cluster sniffing -~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+----------------------------------------------------------------+--------------------------------------------------------------------------+ -| Configure Mattermost to automatically find and connect to | - System Config path: **Environment > Elasticsearch** | -| all data nodes in a cluster. | - ``config.json`` setting: ``".Elasticsearchsettings.Sniff: false",`` | -| | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_SNIFF`` | -| - **true**: Sniffing finds and connects to all data nodes | | -| in your cluster automatically. | | -| - **false**: **(Default)** Cluster sniffing is disabled. | | -+----------------------------------------------------------------+--------------------------------------------------------------------------+ -| Select the **Test Connection** button in the System Console to validate the connection between Mattermost and the Elasticsearch server. | -+----------------------------------------------------------------+--------------------------------------------------------------------------+ - -.. config:setting:: elastic-bulkindexing - :displayname: Bulk indexing (Elasticsearch) - :systemconsole: Environment > Elasticsearch - :configjson: N/A - :environment: N/A - :description: Configure Mattermost to start a bulk index of all existing posts in the database by selecting Index Now. - -Bulk indexing -~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| Configure Mattermost to start a bulk index of all existing | - System Config path: **Environment > Elasticsearch** | -| posts in the database, from oldest to newest. | - ``config.json`` setting: N/A | -| | - Environment variable: N/A | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| **Notes**: | -| | -| - Always `purge indexes <#purge-indexes>`__ before bulk indexing. | -| - Select the **Index Now** button in the System Console to start a bulk index of all posts, and review all index jobs in progress. | -| - Elasticsearch is available during indexing, but search results may be incomplete until the indexing job is complete. | -| - If an in-progress indexing job is canceled, the index and search results will be incomplete. | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ - -.. config:setting:: elastic-rebuildchannelsindex - :displayname: Rebuild channels index (Elasticsearch) - :systemconsole: Environment > Elasticsearch - :configjson: N/A - :environment: N/A - :description: Purge the channels index adn re-index all channels in the database, from oldest to newest. - -Rebuild channels index -~~~~~~~~~~~~~~~~~~~~~~ - -+---------------------------------------------------------------+---------------------------------------------------------------+ -| Purge the channels index adn re-index all channels in the | - System Config path: **Environment > Elasticsearch** | -| database, from oldest to newest. | - ``config.json`` setting: N/A | -| | - Environment variable: N/A | -+---------------------------------------------------------------+---------------------------------------------------------------+ -| Select the **Rebuild Channels Index** button in the System Console to purge the channels index. | -| Ensure no other indexing jobs are in progress via the **Bulk Indexing** table before starting this process. | -| During indexing, channel auto-complete is available, but search results may be incomplete until the indexing job is complete. | -+---------------------------------------------------------------+---------------------------------------------------------------+ - -.. config:setting:: elastic-purgeindexes - :displayname: Purge indexes (Elasticsearch) - :systemconsole: Environment > Elasticsearch - :configjson: N/A - :environment: N/A - :description: Purge the entire Elasticsearch index by selecting Purge Indexes before creating a new index. - -Purge indexes -~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+-------------------------------------------+-------------------------------------------------------------+ -| Purge the entire Elasticsearch index. | - System Config path: **Environment > Elasticsearch** | -| | - ``config.json`` setting: N/A | -| | - Environment variable: N/A | -+-------------------------------------------+-------------------------------------------------------------+ -| Select the **Purge Indexes** button in the System Console to purge the index. | -| After purging the index, create a new index by selecting the **Index Now** button. | -+-------------------------------------------+-------------------------------------------------------------+ - -.. config:setting:: elastic-indexestoskipwhilepurging - :displayname: Indexes to skip while purging (Elasticsearch) - :systemconsole: Environment > Elasticsearch - :configjson: .Elasticsearchsettings.IgnoredPurgeIndexes - :environment: MM_ELASTICSEARCHSETTINGS_IGNOREDPURGEINDEXES - :description: Specify index names to ignore while purging indexes, separated by commas. - -Indexes to skip while purging -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -+---------------------------------------------------------------+---------------------------------------------------------------------------+ -| Specify index names to ignore while purging indexes. | - System Config path: **Environment > Elasticsearch** | -| Separate multiple index names with commas. | - ``config.json`` setting: ``ElasticsearchSettings.IgnoredPurgeIndexes`` | -| | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_IGNOREDPURGEINDEXES`` | -| Use an asterisk (*) to match a sequence of index name | | -| characters. | | -+---------------------------------------------------------------+---------------------------------------------------------------------------+ - -.. config:setting:: elastic-enablesearch - :displayname: Enable Elasticsearch for search queries (Elasticsearch) - :systemconsole: Environment > Elasticsearch - :configjson: .Elasticsearchsettings.EnableSearching - :environment: MM_ELASTICSEARCHSETTINGS_ENABLESEARCHING - :description: Configure Mattermost to use Elasticsearch for all search queries using the latest index. - - - **true**: Elasticsearch is used for all search queries using the latest index. Search results may be incomplete until a bulk index of the existing message database is completed. - - **false**: **(Default)** Relational database search is used for search queries. - -Enable Elasticsearch for search queries -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -.. important:: - - - Core search happens in a relational database and is intended for deployments under about 2-3 million posts and file entries. Beyond that scale, enabling Elasticsearch for search queries is highly recommended. - - If you anticipate your Mattermost server reaching more than 2.5 million posts and file entries, we recommend enabling Elasticsearch for optimum search performance **before** reaching 3 million posts. - - For deployments with over 3 million posts, Elasticsearch with :ref:`dedicated indexing ` and scaled usage resourcing through :doc:`cluster support ` is required to avoid significant performance issues, such as timeouts, with :doc:`message searches ` and :doc:`@mentions `. - -+---------------------------------------------------------------+---------------------------------------------------------------------------------+ -| Configure Mattermost to use Elasticsearch for all search | - System Config path: **Environment > Elasticsearch** | -| queries using the latest index. | - ``config.json`` setting: ``".Elasticsearchsettings.EnableSearching: false",`` | -| | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_ENABLESEARCHING`` | -| - **true**: Elasticsearch is used for all search queries | | -| using the latest index. Search results may be incomplete | | -| until a bulk index of the existing message database is | | -| completed. | | -| - **false**: **(Default)** Database search is used for | | -| search queries. | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+ -| **Note**: If indexing is disabled and then re-enabled after an index is created, purge and rebuild the index to ensure complete search results. | -+---------------------------------------------------------------+---------------------------------------------------------------------------------+ - -.. config:setting:: elastic-enableautocomplete - :displayname: Enable Elasticsearch for autocomplete queries (Elasticsearch) - :systemconsole: Environment > Elasticsearch - :configjson: .Elasticsearchsettings.EnableAutocomplete - :environment: MM_ELASTICSEARCHSETTINGS_ENABLEAUTOCOMPLETE - :description: Configure Mattermost to use Elasticsearch for all autocompletion queries on users and channels using the latest index. - - - **true**: Elasticsearch will be used for all autocompletion queries on users and channels using the latest index. - - **false**: **(Default)** Database autocomplete is used. - -Enable Elasticsearch for autocomplete queries -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+------------------------------------------------------------------------------------+ -| Configure Mattermost to use Elasticsearch for all | - System Config path: **Environment > Elasticsearch** | -| autocompletion queries on users and channels using the | - ``config.json`` setting: ``".Elasticsearchsettings.EnableAutocomplete: false",`` | -| latest index. | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_ENABLEAUTOCOMPLETE`` | -| | | -| - **true**: Elasticsearch will be used for all autocompletion | | -| queries on users and channels using the latest index. | | -| - **false**: **(Default)** Database autocomplete is used. | | -+---------------------------------------------------------------+------------------------------------------------------------------------------------+ -| **Note**: Autocompletion results may be incomplete until a bulk index of the existing users and channels database is finished. | -+---------------------------------------------------------------+------------------------------------------------------------------------------------+ - -.. config:setting:: elastic-postindexreplicas - :displayname: Post index replicas (Elasticsearch) - :systemconsole: N/A - :configjson: .Elasticsearchsettings.PostIndexReplicas - :environment: MM_ELASTICSEARCHSETTINGS_POSTINDEXREPLICAS - :description: The number of replicas to use for each post index. Default is **1**. - -Post index replicas -~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+-------------------------------------------------------------------------------+ -| The number of replicas to use for each post index. | - System Config path: N/A | -| | - ``config.json`` setting: ``".Elasticsearchsettings.PostIndexReplicas: 1",`` | -| Numerical input. Default is **1**. | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_POSTINDEXREPLICAS`` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------+ -| **Important notes**: | -| | -| - If this setting is changed, the changed configuration only applies to newly-created indexes. To apply the change to existing indexes, | -| purge and rebuild the index after changing this setting. | -| - If there are ``n`` data nodes, the number of replicas per shard for each index should be ``n-1``. | -| - If the number of nodes in an Elasticsearch cluster changes, this configuration setting, as well as | -| `Channel Index Replicas <#channel-index-replicas>`__ and `User Index Replicas <#user-index-replicas>`__ must also be updated accordingly. | -+---------------------------------------------------------------+-------------------------------------------------------------------------------+ - -.. config:setting:: elastic-postindexshards - :displayname: Post index shards (Elasticsearch) - :systemconsole: N/A - :configjson: .Elasticsearchsettings.PostIndexShards - :environment: MM_ELASTICSEARCHSETTINGS_POSTINDEXSHARDS - :description: The number of shards to use for each post index. Default is **1**. - -Post index shards -~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+-------------------------------------------------------------------------------+ -| The number of shards to use for each post index. | - System Config path: N/A | -| | - ``config.json`` setting: ``".Elasticsearchsettings.PostIndexShards: 1",`` | -| Numerical input. Default is **1**. | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_POSTINDEXSHARDS`` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------+ -| **Important note**: If this configuration setting is changed, the changed configuration only applies to newly-created indexes. | -| To apply the change to existing indexes, purge and rebuild the index after changing this setting. | -+---------------------------------------------------------------+-------------------------------------------------------------------------------+ - - -.. config:setting:: elastic-channelindexreplicas - :displayname: Channel index replicas (Elasticsearch) - :systemconsole: N/A - :configjson: .Elasticsearchsettings.ChannelIndexReplicas - :environment: MM_ELASTICSEARCHSETTINGS_CHANNELINDEXREPLICAS - :description: The number of replicas to use for each channel index. Default is **1**. - -Channel index replicas -~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+----------------------------------------------------------------------------------+ -| The number of replicas to use for each channel index. | - System Config path: N/A | -| | - ``config.json`` setting: ``".Elasticsearchsettings.ChannelIndexReplicas: 1",`` | -| Numerical input. Default is **1**. | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_CHANNELINDEXREPLICAS`` | -+---------------------------------------------------------------+----------------------------------------------------------------------------------+ -| **Note**: If there are ``n`` data nodes, the number of replicas per shard for each index should be ``n-1``. If the number of nodes in an | -| Elasticsearch cluster changes, this configuration setting, as well as `Post Index Replicas <#post-index-shards>`__ and | -| `User Index Replicas <#user-index-replicas>`__ must also be updated accordingly. | -+---------------------------------------------------------------+----------------------------------------------------------------------------------+ - -.. config:setting:: elastic-channelindexshards - :displayname: Channel index shards (Elasticsearch) - :systemconsole: N/A - :configjson: .Elasticsearchsettings.ChannelIndexShards - :environment: MM_ELASTICSEARCHSETTINGS_CHANNELINDEXSHARDS - :description: The number of shards to use for each channel index. Default is **1**. - -Channel index shards -~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+----------------------------------------------------------------------------------+ -| The number of shards to use for each channel index. | - System Config path: N/A | -| | - ``config.json`` setting: ``".Elasticsearchsettings.ChannelIndexShards: 1",`` | -| Numerical input. Default is **1**. | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_CHANNELINDEXSHARDS`` | -+---------------------------------------------------------------+----------------------------------------------------------------------------------+ - -.. config:setting:: elastic-userindexreplicas - :displayname: User index replicas (Elasticsearch) - :systemconsole: N/A - :configjson: .Elasticsearchsettings.UserIndexReplicas - :environment: MM_ELASTICSEARCHSETTINGS_USERINDEXREPLICAS - :description: The number of replicas to use for each user index. Default is **1**. - -User index replicas -~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+-------------------------------------------------------------------------------+ -| The number of replicas to use for each user index. | - System Config path: N/A | -| | - ``config.json`` setting: ``".Elasticsearchsettings.UserIndexReplicas: 1",`` | -| Numerical input. Default is **1**. | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_USERINDEXREPLICAS`` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------+ -| **Note**: If there are ``n`` data nodes, the number of replicas per shard for each index should be ``n-1``. If the number of nodes in an | -| Elasticsearch cluster changes, this configuration setting, as well as `Post Index Replicas <#post-index-replicas>`__ and | -| `Channel Index Replicas <#channel-index-replicas>`__ must also be updated accordingly. | -+---------------------------------------------------------------+-------------------------------------------------------------------------------+ - -.. config:setting:: elastic-userindexshards - :displayname: User index shards (Elasticsearch) - :systemconsole: N/A - :configjson: .Elasticsearchsettings.UserIndexShards - :environment: MM_ELASTICSEARCHSETTINGS_USERINDEXSHARDS - :description: The number of shards to use for each user index. Default is **1**. - -User index shards -~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+----------------------------------------------------------------------------------+ -| The number of shards to use for each user index. | - System Config path: N/A | -| | - ``config.json`` setting: ``".Elasticsearchsettings.UserIndexShards: 1",`` | -| Numerical input. Default is **1**. | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_USERINDEXSHARDS`` | -+---------------------------------------------------------------+----------------------------------------------------------------------------------+ - -.. config:setting:: elastic-aggregatesearchindexes - :displayname: Aggregate search indexes (Elasticsearch) - :systemconsole: N/A - :configjson: .Elasticsearchsettings.AggregatePostsAfterDays - :environment: MM_ELASTICSEARCHSETTINGS_AGGREGATEPOSTSAFTERDAYS - :description: Elasticsearch indexes older than the age specified by this setting, in days, will be aggregated during the daily scheduled job. Default is **365** days. - -Aggregate search indexes -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+----------------------------------------------------------------------------------------+ -| Elasticsearch indexes older than the age specified by this | - System Config path: N/A | -| setting, in days, will be aggregated during the daily | - ``config.json`` setting: ``".Elasticsearchsettings.AggregatePostsAfterDays: 365",`` | -| scheduled job. | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_AGGREGATEPOSTSAFTERDAYS`` | -| | | -| Numerical input. Default is **365** days. | | -+---------------------------------------------------------------+----------------------------------------------------------------------------------------+ -| **Note**: If you’re using :doc:`data retention ` and | -| :doc:`Elasticsearch `, configure this with a value greater than your data retention policy. | -+---------------------------------------------------------------+----------------------------------------------------------------------------------------+ - -.. config:setting:: elastic-postaggregatorstarttime - :displayname: Post aggregator start time (Elasticsearch) - :systemconsole: N/A - :configjson: .Elasticsearchsettings.PostsAggregatorJobStartTime - :environment: MM_ELASTICSEARCHSETTINGS_POSTSAGGREGATORJOBSTARTTIME - :description: The start time of the daily scheduled aggregator job. Must be a 24-hour time stamp in the form ``HH:MM`` based on the local time of the server. Default is **03:00** (3 AM). - -Post aggregator start time -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+ -| The start time of the daily scheduled aggregator job. | - System Config path: N/A | -| | - ``config.json`` setting: ``".Elasticsearchsettings.PostsAggregatorJobStartTime: 03:00",`` | -| Must be a 24-hour time stamp in the form ``HH:MM`` based on | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_POSTSAGGREGATORJOBSTARTTIME`` | -| the local time of the server. | | -| | | -| Default is **03:00** (3 AM) | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+ - -.. config:setting:: elastic-indexprefix - :displayname: Index prefix (Elasticsearch) - :systemconsole: N/A - :configjson: .Elasticsearchsettings.IndexPrefix - :environment: MM_ELASTICSEARCHSETTINGS_INDEXPREFIX - :description: The prefix added to the Elasticsearch index name. - -Index prefix -~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| The prefix added to the Elasticsearch index name. | - System Config path: N/A | -| | - ``config.json`` setting: ``".Elasticsearchsettings.IndexPrefix",`` | -| | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_INDEXPREFIX`` | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| **Note**: When this setting is used, all Elasticsearch indexes created by Mattermost are given this prefix. You can set different | -| prefixes so that multiple Mattermost deployments can share an Elasticsearch cluster without the index names colliding. | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ - -.. config:setting:: elastic-liveindexingbatchsize - :displayname: Live indexing batch size (Elasticsearch) - :systemconsole: N/A - :configjson: .Elasticsearchsettings.LiveIndexingBatchSize - :environment: MM_ELASTICSEARCHSETTINGS_LIVEINDEXINGBATCHSIZE - :description: The number of new posts batched together before they're added to the Elasticsearch index. Default is **1**. - -Live indexing batch size -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+-----------------------------------------------------------------------------------+ -| The number of new posts needed before those posts are added | - System Config path: N/A | -| to the Elasticsearch index. Once added to the Index, | - ``config.json`` setting: ``".Elasticsearchsettings.LiveIndexingBatchSize: 1",`` | -| the post becomes searchable. | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_LIVEINDEXINGBATCHSIZE`` | -| | | -| On servers with more than 1 post per second, we suggest | | -| setting this value to the average number of posts over a | | -| 20 second period of time. | | -| | | -| Numerical input. Default is **1**. Every post is indexed | | -| synchronously as they are created. | | -+---------------------------------------------------------------+-----------------------------------------------------------------------------------+ -| **Note**: It may be necessary to increase this value to avoid hitting the rate limit or resource limit of your Elasticsearch cluster | -| on installs handling more than 1 post per second. | -| | -| **What exactly happens when I increase this value?** | -| The primary impact is that a post will be indexed into Elasticsearch after the threshold of posts is met which then makes the posts searchable | -| within Mattermost. So, if you set this based on our recommendations for larger servers, and you make a post, you cannot find it via search | -| for ~ 10-20 seconds, on average. Realistically, no users should see or feel this impact due to the limited amount of users who are actively | -| **searching** for a post this quickly. You can set this value to a lower average or higher average as well, depending on your Elasticsearch | -| server specifications. | -| | -| During busy periods, this delay will be faster as more traffic is happening, causing more posts and a quicker time to hit the index number. | -| During slow times, expect the reverse. | -+---------------------------------------------------------------+-----------------------------------------------------------------------------------+ - -**How to find the right number for your server** - -1. You must understand how many posts your server makes every minute. Run the query below to calculate your server's average posts per minute. - - Note that this query can be heavy, so we recommend that you run it during non-peak hours. - Additionally, you can adjust the ``WHERE`` clause to see the posts per minute over a different time period. Right now ``31536000000`` represents the number of milliseconds in a year. - - .. code-block:: SQL - - SELECT - AVG(postsPerMinute) as averagePostsPerMinute - FROM ( - SELECT - count(*) as postsPerMinute, - date_trunc('minute', to_timestamp(createat/1000)) - FROM posts - WHERE createAt > ( (extract(epoch from now()) * 1000 ) - 31536000000) - GROUP BY date_trunc('minute', to_timestamp(createat/1000)) - ) as ppm; - -2. Decide the acceptable index window for your environment, and divide your average posts per minute by that. We suggest 10-20 seconds. Assuming you have ``600`` posts per minute on average, and you want to index every 20 seconds (``60 seconds / 20 seconds = 3```) you would calculate ``600 / 3`` to come to the number ``200``. After 200 posts, Mattermost will index the posts into Elasticsearch. So, on average, there would be a 20-second delay in searchability. - -3. Edit the ``config.json`` or run mmctl to modify the ``LiveIndexingBatchSize`` setting - - **In the ``config.json``** - - .. code-block:: JSON - - { - "ElasticsearchSettings": { - "LiveIndexingBatchSize": 200 - } - } - - **Via mmctl** - - .. code-block:: sh - - mmctl config set ElasticsearchSettings.LiveIndexingBatchSize 200 - - **Via an environment variable** - - .. code-block:: sh - - MM_ELASTICSEARCHSETTINGS_LIVEINDEXINGBATCHSIZE = 200 - -4. Restart the Mattermost server. - -.. config:setting:: elastic-batchsize - :displayname: Batch size (Elasticsearch) - :systemconsole: N/A - :configjson: .Elasticsearchsettings.BatchSize - :environment: MM_ELASTICSEARCHSETTINGS_BATCHSIZE - :description: The number of posts for a single batch during a bulk indexing job. Default is **10000**. - -Batch size -~~~~~~~~~~~ - -+-------------------------------------------+---------------------------------------------------------------------------+ -| The number of posts for a single batch | - System Config path: N/A | -| during a bulk indexing job. | - ``config.json`` setting: ``".Elasticsearchsettings.BatchSize :10000",`` | -| | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_BATCHSIZE`` | -| Numerical input. Default is **10000**. | | -+-------------------------------------------+---------------------------------------------------------------------------+ - -.. config:setting:: elastic-requesttimeout - :displayname: Request timeout (Elasticsearch) - :systemconsole: N/A - :configjson: .Elasticsearchsettings.RequestTimeoutSeconds - :environment: MM_ELASTICSEARCHSETTINGS_REQUESTTIMEOUTSECONDS - :description: The timeout, in seconds, for Elasticsearch calls. Default is **30** seconds. - -Request timeout -~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+------------------------------------------------------------------------------------+ -| The timeout, in seconds, for Elasticsearch calls. | - System Config path: N/A | -| | - ``config.json`` setting: ``".Elasticsearchsettings.RequestTimeoutSeconds :30",`` | -| Numerical input in seconds. Default is **30** seconds. | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_REQUESTTIMEOUTSECONDS`` | -+---------------------------------------------------------------+------------------------------------------------------------------------------------+ - -.. config:setting:: elastic-trace - :displayname: Trace (Elasticsearch) - :systemconsole: N/A - :configjson: .Elasticsearchsettings.Trace - :environment: MM_ELASTICSEARCHSETTINGS_TRACE - :description: Options for printing Elasticsearch trace errors. - - - **error**: Creates the error trace when initializing the Elasticsearch client and prints any template creation or search query that returns an error as part of the error message. - - **all**: Creates the three traces (error, trace and info) for the driver and doesn’t print the queries because they will be part of the trace log level of the driver. - - **not specified**: **(Default)** No error trace is created. - -Trace -~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| Options for printing Elasticsearch trace errors. | - System Config path: N/A | -| | - ``config.json`` setting: ``".Elasticsearchsettings.Trace",`` | -| - **error**: Creates the error trace when initializing | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_TRACE`` | -| the Elasticsearch client and prints any template creation | | -| or search query that returns an error as part of the | | -| error message. | | -| - **all**: Creates the three traces (error, trace and info) | | -| for the driver and doesn’t print the queries because they | | -| will be part of the trace log level of the driver. | | -| - **not specified**: **(Default)** No error trace is created. | | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ diff --git a/source/configure/enable-copilot.rst b/source/configure/enable-copilot.rst index 2b0d9a4b585..a96f0f5d6b1 100644 --- a/source/configure/enable-copilot.rst +++ b/source/configure/enable-copilot.rst @@ -109,7 +109,7 @@ Disabling tools will prevent the LLM from making function calls. This is useful Copilot plugin metrics ----------------------- -Metrics for Copilot are exposed through the ``/plugins/mattermost-ai/metrics`` subpath under the existing Mattermost server metrics endpoint. This is controlled by the :ref:`Listen address for performance ` configuration setting. It defaults to port ``8067``, and the following metrics are available: +Metrics for Copilot are exposed through the ``/plugins/mattermost-ai/metrics`` subpath under the existing Mattermost server metrics endpoint. This is controlled by the :ref:`Listen address for performance ` configuration setting. It defaults to port ``8067``, and the following metrics are available: - ``copilot_system_plugin_start_timestamp_seconds``: The time the plugin started. - ``copilot_system_plugin_info``: The plugin version and installation ID. diff --git a/source/configure/environment-configuration-settings.rst b/source/configure/environment-configuration-settings.rst index 3dd3a397696..7e5449be889 100644 --- a/source/configure/environment-configuration-settings.rst +++ b/source/configure/environment-configuration-settings.rst @@ -4,74 +4,2978 @@ Environment configuration settings .. include:: ../_static/badges/allplans-selfhosted.rst :start-after: :nosearch: -.. include:: common-config-settings-notation.rst - :start-after: :nosearch: +.. tip:: + + Each configuration value below includes a JSON path to access the value programmatically in the ``config.json`` file using a JSON-aware tool. For example, the ``SiteURL`` value is under ``ServiceSettings``. + + - If using a tool such as `jq `__, you'd enter: ``cat config/config.json | jq '.ServiceSettings.SiteURL'`` + - When working with the ``config.json`` file manually, look for the key ``ServiceSettings``, then within that object, find the key ``SiteURL``. + +Both self-hosted and Cloud admins can access the following configuration settings in **System Console > Environment**. Self-hosted admins can also edit the ``config.json`` file as described in the following tables. + +Web server +---------- + +.. include:: ../_static/badges/allplans-selfhosted.rst + :start-after: :nosearch: + +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. + +.. config:setting:: web-siteurl + :displayname: Site URL (Web Server) + :systemconsole: Environment > Web Server + :configjson: .ServiceSettings.SiteURL + :environment: MM_SERVICESETTINGS_SITEURL + :description: The URL that users use to access Mattermost. The port number is required if it’s not a standard port, such as 80 or 443. + +Site URL +~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+---------------------------------------------------------------+ +| The URL that users use to access Mattermost. | - System Config path: **Environment > Web Server** | +| The port number is required if it’s not a standard port, | - ``config.json`` setting: ``.ServiceSettings.SiteURL",`` | +| such as 80 or 443. This field is required. | - Environment variable: ``MM_SERVICESETTINGS_SITEURL`` | +| | | +| Select the **Test Live URL** button in the System Console | | +| to validate the Site URL. | | ++---------------------------------------------------------------+---------------------------------------------------------------+ +| **Notes**: | +| | +| - The URL may contain a subpath, such as ``https://example.com/company/mattermost``. | +| - If you change the Site URL value, log out of the Desktop App, and sign back in using the new domain. | +| - If Site URL is not set: | +| | +| - Email notifications will contain broken links, and email batching will not work. | +| - Authentication via OAuth 2.0, including GitLab, Google, and Entra ID, will fail. | +| - Plugins may not work as expected. | ++-------------------------------------------------------------------------------------------------------------------------------+ + +.. config:setting:: max-url-length + :displayname: Maximum URL length (Web Server) + :systemconsole: N/A + :configjson: .ServiceSettings.MaximumURLLength + :environment: MM_SERVICESETTINGS_MAXIMUMURLLENGTH + :description: The longest URL, in characters, including query parameters, accepted by the Mattermost server. Default is 2048 characters. + +Maximum URL length +~~~~~~~~~~~~~~~~~~ + ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| The longest URL, in characters, including query parameters, | - System Config path: N/A | +| accepted by the Mattermost server. Longer URLs are rejected, | - ``config.json`` setting: ``.ServiceSettings.MaximumURLLength: 2048",`` | +| and API calls fail with an error. | - Environment variable: ``MM_SERVICESETTINGS_MAXIMUMURLLENGTH`` | +| | | +| Numeric value. Default is **2048** characters. | | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ + +.. config:setting:: web-listenaddress + :displayname: Web server listen address (Web Server) + :systemconsole: Environment > Web Server + :configjson: .ServiceSettings.ListenAddress + :environment: MM_SERVICESETTINGS_LISTENADDRESS + + The address and port to which to bind and listen. Specifying ``:8065`` will bind to all network interfaces. + Specifying ``127.0.0.1:8065`` will only bind to the network interface having that IP address. + +Web server listen address +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+------------------------------------------------------------------+ +| The address and port to which to bind and listen. | - System Config path: **Environment > Web Server** | +| Specifying ``:8065`` will bind to all network interfaces. | - ``config.json`` setting: ``".ServiceSettings.ListenAddress",`` | +| Specifying ``127.0.0.1:8065`` will only bind to the network | - Environment variable: ``MM_SERVICESETTINGS_LISTENADDRESS`` | +| interface having that IP address. | | +| | | +| If you choose a port of a lower level (called “system ports” | | +| or “well-known ports”, in the range of 0-1023), you must have | | +| permissions to bind to that port. | | ++---------------------------------------------------------------+------------------------------------------------------------------+ + +.. config:setting:: web-forwardinsecure + :displayname: Forward port 80 to 443 (Web Server) + :systemconsole: Environment > Web Server + :configjson: .ServiceSettings.Forward80To443 + :environment: MM_SERVICESETTINGS_FORWARD80TO443 + + - **true**: Forwards all insecure traffic from port 80 to secure port 443. + - **false**: **(Default)** When using a proxy such as NGINX in front of Mattermost this setting is unnecessary and should be set to false. + +Forward port 80 to 443 +~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| Forward insecure traffic from port 80 to port 443. | - System Config path: **Environment > Web Server** | +| | - ``config.json`` setting: ``".ServiceSettings.Forward80To443: false",`` | +| - **true**: Forwards all insecure traffic from port 80 to | - Environment variable: ``MM_SERVICESETTINGS_FORWARD80TO443`` | +| secure port 443. | | +| - **false**: **(Default)** When using a proxy such as NGINX | | +| in front of Mattermost this setting is unnecessary | | +| and should be set to false. | | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ + +.. config:setting:: web-connectionsecurity + :displayname: Web server connection security (Web Server) + :systemconsole: Environment > Web Server + :configjson: .ServiceSettings.ConnectionSecurity + :environment: MM_SERVICESETTINGS_CONNECTIONSECURITY + :description: Connection security between Mattermost clients and the server. + + - **Not specified**: Mattermost will connect over an unsecure connection. + - **TLS**: Encrypts the communication between Mattermost clients and your server. + +Web server connection security +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++-----------------------------------------------------------------------+-----------------------------------------------------------------------+ +| Connection security between Mattermost clients and the server. | - System Config path: **Environment > Web Server** | +| | - ``config.json`` setting: ``".ServiceSettings.ConnectionSecurity",`` | +| - **Not specified**: Mattermost will connect over an unsecure | - Environment variable: ``MM_SERVICESETTINGS_CONNECTIONSECURITY`` | +| connection. | | +| - **TLS**: Encrypts the communication between Mattermost | | +| clients and your server. See the :doc:`configuring TLS on | | +| Mattermost ` for more details. | | ++-----------------------------------------------------------------------+-----------------------------------------------------------------------+ + +.. config:setting:: web-tlscertificatefile + :displayname: TLS certificate file (Web Server) + :systemconsole: Environment > Web Server + :configjson: .ServiceSettings.TLSCertFile + :environment: MM_SERVICESETTINGS_TLSCERTFILE + :description: The path to the certificate file to use for TLS connection security. + +TLS certificate file +~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++--------------------------------------------------------+------------------------------------------------------------------+ +| The path to the certificate file to use for TLS | - System Config path: **Environment > Web Server** | +| connection security. | - ``config.json`` setting: ``".ServiceSettings.TLSCertFile",`` | +| | - Environment variable: ``MM_SERVICESETTINGS_TLSCERTFILE`` | +| String input. | | ++--------------------------------------------------------+------------------------------------------------------------------+ + +.. config:setting:: web-tlskeyfile + :displayname: TLS key file (Web Server) + :systemconsole: Environment > Web Server + :configjson: .ServiceSettings.TLSKeyFile + :environment: MM_SERVICESETTINGS_TLSKEYFILE + :description: The path to the TLS key file to use for TLS connection security. + +TLS key file +~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++--------------------------------------------------------+---------------------------------------------------------------+ +| The path to the TLS key file to use for TLS | - System Config path: **Environment > Web Server** | +| connection security. | - ``config.json`` setting: ``".ServiceSettings.TLSKeyFile",`` | +| | - Environment variable: ``MM_SERVICESETTINGS_TLSKEYFILE`` | +| String input. | | ++--------------------------------------------------------+---------------------------------------------------------------+ + +.. config:setting:: web-useletsencrypt + :displayname: Use Let's Encrypt (Web Server) + :systemconsole: Environment > Web Server + :configjson: .ServiceSettings.UseLetsEncrypt + :environment: MM_SERVICESETTINGS_USELETSENCRYPT + :description: Enable the automatic retrieval of certificates from Let’s Encrypt. + + - **true**: The certificate will be retrieved when a client attempts to connect from a new domain. This will work with multiple domains. + - **false**: **(Default)** Manual certificate specification based on the TLS Certificate File and TLS Key File specified above. + +Use Let's Encrypt +~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++-----------------------------------------------------------------------------------------------+--------------------------------------------------------------------------+ +| Enable the automatic retrieval of certificates from Let’s Encrypt. | - System Config path: **Environment > Web Server** | +| See the :doc:`configuring TLS on Mattermost documentation ` | - ``config.json`` setting: ``".ServiceSettings.UseLetsEncrypt: false",`` | +| for more details on setting up Let’s Encrypt. | - Environment variable: ``MM_SERVICESETTINGS_USELETSENCRYPT`` | +| | | +| - **true**: The certificate will be retrieved when a client | | +| attempts to connect from a new domain. This will work with | | +| multiple domains. | | +| - **false**: **(Default)** Manual certificate specification | | +| based on the TLS Certificate File and TLS Key File specified | | +| above. | | ++-----------------------------------------------------------------------------------------------+--------------------------------------------------------------------------+ + +.. config:setting:: web-letsencryptcache + :displayname: Let's Encrypt certificate cache file (Web Server) + :systemconsole: Environment > Web Server + :configjson: .ServiceSettings.LetsEncryptCertificateCacheFile + :environment: MM_SERVICESETTINGS_LETSENCRYPTCERTIFICATECACHEFILE + :description: The path to the file where certificates and other data about the Let’s Encrypt service will be stored. + +Let's Encrypt certificate cache file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++--------------------------------------------------------+------------------------------------------------------------------------------------+ +| The path to the file where certificates and other data | - System Config path: **Environment > Web Server** | +| about the Let’s Encrypt service will be stored. | - ``config.json`` setting: ``".ServiceSettings.LetsEncryptCertificateCacheFile",`` | +| | - Environment variable: ``MM_SERVICESETTINGS_LETSENCRYPTCERTIFICATECACHEFILE`` | +| File path input. | | ++--------------------------------------------------------+------------------------------------------------------------------------------------+ + +.. config:setting:: web-readtimeout + :displayname: Read timeout (Web Server) + :systemconsole: Environment > Web Server + :configjson: .ServiceSettings.ReadTimeout + :environment: MM_SERVICESETTINGS_READTIMEOUT + :description: Maximum time allowed from when the connection is accepted to when the request body is fully read. Default is **300** seconds. + +Read timeout +~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------+---------------------------------------------------------------------+ +| Maximum time allowed from when the connection is | - System Config path: **Environment > Web Server** | +| accepted to when the request body is fully read. | - ``config.json`` setting: ``".ServiceSettings.ReadTimeout: 300",`` | +| | - Environment variable: ``MM_SERVICESETTINGS_READTIMEOUT`` | +| Numerical input in seconds. Default is **300** seconds. | | ++---------------------------------------------------------+---------------------------------------------------------------------+ + +.. config:setting:: web-writetimeout + :displayname: Write timeout (Web Server) + :systemconsole: Environment > Web Server + :configjson: .ServiceSettings.WriteTimeout + :environment: MM_SERVICESETTINGS_WRITETIMEOUT + + If using HTTP (insecure), this is the maximum time, in seconds, allowed from the end of reading the request headers until the response is written. + If using HTTPS, it's the total time, in seconds, from when the connection is accepted until the response is written. + Default is 300 seconds. + +Write timeout +~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++----------------------------------------------------------+-----------------------------------------------------------------------------+ +| - If using HTTP (insecure), this is the maximum time | - System Config path: **Environment > Web Server** | +| allowed from the end of reading the request headers | - ``config.json`` setting: ``".ServiceSettings.WriteTimeout: 300",`` | +| until the response is written. | - Environment variable: ``MM_SERVICESETTINGS_WRITETIMEOUT`` | +| - If using HTTPS, it's the total time from when the | | +| connection is accepted until the response is written. | | +| | | +| Numerical input in seconds. Default is **300** seconds. | | ++----------------------------------------------------------+-----------------------------------------------------------------------------+ + +.. config:setting:: web-idletimeout + :displayname: Idle timeout (Web Server) + :systemconsole: Environment > Web Server + :configjson: .ServiceSettings.IdleTimeout + :environment: MM_SERVICESETTINGS_IDLETIMEOUT + :description: This is the maximum time, in seconds, allowed before an idle connection is disconnected. Default is **300** seconds. + +Idle timeout +~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------+---------------------------------------------------------------------+ +| Set an explicit idle timeout in the HTTP server. | - System Config path: **Environment > Web Server** | +| This is the maximum time allowed before an idle | - ``config.json`` setting: ``".ServiceSettings.IdleTimeout: 300",`` | +| connection is disconnected. | - Environment variable: ``MM_SERVICESETTINGS_IDLETIMEOUT`` | +| | | +| Numerical input in seconds. Default is **300** seconds. | | ++---------------------------------------------------------+---------------------------------------------------------------------+ + +.. config:setting:: web-webservermode + :displayname: Webserver mode (Web Server) + :systemconsole: Environment > Web Server + :configjson: .ServiceSettings.WebserverMode + :environment: MM_SERVICESETTINGS_WEBSERVERMODE + + - **gzip**: **(Default)** The Mattermost server will serve static files compressed with gzip to improve performance. + - **Uncompressed**: The Mattermost server will serve static files uncompressed. + - **Disabled**: The Mattermost server will not serve static files. + +Webserver mode +~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------------+------------------------------------------------------------------------+ +| We recommend gzip to improve performance unless your | - System Config path: **Environment > Web Server** | +| environment has specific restrictions, such as a web proxy that | - ``config.json`` setting: ``".ServiceSettings.WebserverMode: gzip",`` | +| distributes gzip files poorly. | - Environment variable: ``MM_SERVICESETTINGS_WEBSERVERMODE`` | +| | | +| - **gzip**: **(Default)** The Mattermost server will serve static | | +| files compressed with gzip to improve performance. | | +| gzip compression applies to the HTML, CSS, Javascript, and other | | +| static content files that make up the Mattermost web client. | | +| - **Uncompressed**: The Mattermost server will serve static | | +| files uncompressed. | | +| - **Disabled**: The Mattermost server will not serve static files. | | ++---------------------------------------------------------------------+------------------------------------------------------------------------+ + +.. config:setting:: web-insecureoutgoingconnections + :displayname: Enable insecure outgoing connections (Web Server) + :systemconsole: Environment > Web Server + :configjson: .ServiceSettings.EnableInsecureOutgoingConnections + :environment: MM_SERVICESETTINGS_ENABLEINSECUREOUTGOINGCONNECTIONS + + - **true**: Outgoing HTTPS requests, including S3 clients, can accept unverified, self-signed certificates. + - **false**: **(Default)** Only secure HTTPS requests are allowed. + +Enable insecure outgoing connections +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+---------------------------------------------------------------------------------------------+ +| Configure Mattermost to allow insecure outgoing connections. | - System Config path: **Environment > Web Server** | +| | - ``config.json`` setting: ``".ServiceSettings.EnableInsecureOutgoingConnections: false",`` | +| - **true**: Outgoing HTTPS requests, including S3 clients, | - Environment variable: ``MM_SERVICESETTINGS_ENABLEINSECUREOUTGOINGCONNECTIONS`` | +| can accept unverified, self-signed certificates. | | +| For example, outgoing webhooks to a server with a | | +| self-signed TLS certificate, using any domain, will be | | +| allowed, and will skip TLS verification. | | +| - **false**: **(Default)** Only secure HTTPS requests are | | +| allowed. | | ++---------------------------------------------------------------+---------------------------------------------------------------------------------------------+ +| **Security note**: Enabling this feature makes these connections susceptible to man-in-the-middle attacks. | ++---------------------------------------------------------------+---------------------------------------------------------------------------------------------+ + +.. config:setting:: web-managedresourcepaths + :displayname: Managed resource paths (Web Server) + :systemconsole: Environment > Web Server + :configjson: .ServiceSettings.ManagedResourcePaths + :environment: MM_SERVICESETTINGS_MANAGEDRESOURCEPATHS + :description: A comma-separated list of paths within the Mattermost domain that are managed by a third party service instead of Mattermost itself. + +Managed resource paths +~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++--------------------------------------------------------+-------------------------------------------------------------------------+ +| A comma-separated list of paths within the Mattermost | - System Config path: **Environment > Web Server** | +| domain that are managed by a third party service | - ``config.json`` setting: ``".ServiceSettings.ManagedResourcePaths",`` | +| instead of Mattermost itself. | - Environment variable: ``MM_SERVICESETTINGS_MANAGEDRESOURCEPATHS`` | +| | | +| Links to these paths will be opened in a new | | +| tab/window by Mattermost apps. | | +| | | +| For example, if Mattermost is running on | | +| ``https://mymattermost.com``, setting this to | | +| conference will cause links such as | | +| ``https://mymattermost.com/conference`` to open in a | | +| new window. | | ++--------------------------------------------------------+-------------------------------------------------------------------------+ +| **Note:** | +| When using the Mattermost Desktop App, additional configuration is required to open the link within the Desktop App instead of | +| in a browser. See the :doc:`desktop managed resources ` | +| documentation for details. | ++--------------------------------------------------------+-------------------------------------------------------------------------+ + +Reload configuration from disk +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: ../_static/badges/ent-only.rst + :start-after: :nosearch: + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++----------------------------------------------------------+---------------------------------------------------------------+ +| You must change the database line in the ``config.json`` | - System Config path: **Environment > Web Server** | +| file, and then reload configuration to fail over | - ``config.json`` setting: N/A | +| without taking the server down. | - Environment variable: N/A | +| | | +| Select the **Reload configuration from disk** button | | +| in the System Console after changing your database | | +| configuration. Then, go to **Environment > Database** | | +| and select **Recycle Database Connections** to | | +| complete the reload. | | ++----------------------------------------------------------+---------------------------------------------------------------+ + +Purge all caches +~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++----------------------------------------------------------+---------------------------------------------------------------+ +| Purge all in-memory caches for sessions, accounts, | - System Config path: **Environment > Web Server** | +| and channels. | - ``config.json`` setting: N/A | +| | - Environment variable: N/A | +| Select the **Purge All Caches** button in the System | | +| Console to purge all caches. | | ++----------------------------------------------------------+---------------------------------------------------------------+ +| **Note**: Purging the caches may adversely impact performance. | +| :doc:`high availability cluster-based deployments ` will attempt | +| to purge all the servers in the cluster | ++----------------------------------------------------------+---------------------------------------------------------------+ + +.. config:setting:: web-websocketurl + :displayname: Websocket URL (Web Server) + :systemconsole: N/A + :configjson: .ServiceSettings.WebsocketURL + :environment: MM_SERVICESETTINGS_WEBSOCKETURL + :description: You can configure the server to instruct clients on where they should try to connect websockets to. + +Websocket URL +~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++--------------------------------------------------------+---------------------------------------------------------------------+ +| You can configure the server to instruct clients | - System Config path: N/A | +| on where they should try to connect websockets to. | - ``config.json`` setting: ``".ServiceSettings.WebsocketURL: "",`` | +| | - Environment variable: ``MM_SERVICESETTINGS_WEBSOCKETURL`` | +| String input. | | ++--------------------------------------------------------+---------------------------------------------------------------------+ +| **Note**: We strongly recommend configuring a single websocket URL that matches the `Site URL <#site-url>`_ configuration | +| setting. | ++--------------------------------------------------------+---------------------------------------------------------------------+ + +.. config:setting:: web-licensefilelocation + :displayname: License file location (Web Server) + :systemconsole: N/A + :configjson: .ServiceSettings.LicenseFileLocation + :environment: MM_SERVICESETTINGS_LICENSEFILELOCATION + :description: The path and filename of the license file on disk. + +License file location +~~~~~~~~~~~~~~~~~~~~~ + +.. include:: ../_static/badges/ent-pro-only.rst + :start-after: :nosearch: + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++--------------------------------------------------------+----------------------------------------------------------------------------+ +| The path and filename of the license file on disk. | - System Config path: N/A | +| On startup, if Mattermost can't find a valid license | - ``config.json`` setting: ``".ServiceSettings.LicenseFileLocation: "",`` | +| in the database from a previous upload, it looks in | - Environment variable: ``MM_SERVICESETTINGS_LICENSEFILELOCATION`` | +| this path for the license file. | | +| | | +| String input. Can be an absolute path or a path | | +| relative to the ``mattermost`` directory. | | ++--------------------------------------------------------+----------------------------------------------------------------------------+ + +.. config:setting:: web-tlsminimumversion + :displayname: TLS minimum version (Web Server) + :systemconsole: N/A + :configjson: .ServiceSettings.TLSMinVer + :environment: MM_SERVICESETTINGS_TLSMINVER + :description: The minimum TLS version used by the Mattermost server. Default value is **1.2**. + +TLS minimum version +~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++--------------------------------------------------------+---------------------------------------------------------------------+ +| The minimum TLS version used by the Mattermost server. | - System Config path: N/A | +| | - ``config.json`` setting: ``".ServiceSettings.TLSMinVer: 1.2",`` | +| String input. Default is **1.2**. | - Environment variable: ``MM_SERVICESETTINGS_TLSMINVER`` | ++--------------------------------------------------------+---------------------------------------------------------------------+ +| **Note**: This setting only takes effect if you are using the built-in server binary directly, and not using a reverse proxy | +| layer, such as NGINX. | ++--------------------------------------------------------+---------------------------------------------------------------------+ + +.. config:setting:: web-trustedproxyipheader + :displayname: Trusted proxy IP header (Web Server) + :systemconsole: N/A + :configjson: .ServiceSettings.TrustedProxyIPHeader + :environment: MM_SERVICESETTINGS_TRUSTEDPROXYIPHEADER + :description: Specified headers that will be checked, one by one, for IP addresses (order is important). All other headers are ignored. + +Trusted proxy IP header +~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++--------------------------------------------------------+------------------------------------------------------------------------------+ +| Specified headers that will be checked, one by one, | - System Config path: N/A | +| for IP addresses (order is important). | - ``config.json`` setting: ``".ServiceSettings.TrustedProxyIPHeader: []",`` | +| All other headers are ignored. | - Environment variable: ``MM_SERVICESETTINGS_TRUSTEDPROXYIPHEADER`` | +| | | +| String array input consisting of header names, | | +| such as ``["X-Forwarded-For", "X-Real-Ip"]``. | | ++--------------------------------------------------------+------------------------------------------------------------------------------+ +| **Notes**: | +| | +| - The default value of ``[]`` means that no header will be trusted. Prior to v5.12, the absence of this configuration setting entry | +| will have it set to ``["X-Forwarded-For", "X-Real-Ip"]`` on upgrade to maintain backwards compatibility. | +| - We recommend keeping the default setting when Mattermost is running without a proxy to avoid the client sending the headers and | +| bypassing rate limiting and/or the audit log. | +| - For environments that use a reverse proxy, this issue does not exist, provided that the headers are set by the reverse proxy. | +| In those environments, only explicitly whitelist the header set by the reverse proxy and no additional values. | +| | +| | ++--------------------------------------------------------+------------------------------------------------------------------------------+ + +.. config:setting:: web-enablehsts + :displayname: Enable Strict Transport Security (HSTS) (Web Server) + :systemconsole: N/A + :configjson: .ServiceSettings.TLSStrictTransport + :environment: MM_SERVICESETTINGS_TLSSTRICTTRANSPORT + + - **true**: Adds the Strict Transport Security (HSTS) header to all responses, forcing the browser to request all resources via HTTPS. + - **false**: **(Default)** No restrictions on TLS transport. Strict Transport Security (HSTS) header isn't added to responses. + +Enable Strict Transport Security (HSTS) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++--------------------------------------------------------+-------------------------------------------------------------------------------+ +| - **true**: Adds the Strict Transport Security (HSTS) | - System Config path: N/A | +| header to all responses, forcing the browser to | - ``config.json`` setting: ``".ServiceSettings.TLSStrictTransport: false",`` | +| request all resources via HTTPS. | - Environment variable: ``MM_SERVICESETTINGS_TLSSTRICTTRANSPORT`` | +| - **false**: **(Default)** No restrictions on TLS | | +| transport. Strict Transport Security (HSTS) header | | +| isn't added to responses. | | ++--------------------------------------------------------+-------------------------------------------------------------------------------+ +| See the `Strict-Transport-Security `__ | +| documentation for details. | ++--------------------------------------------------------+-------------------------------------------------------------------------------+ + +.. config:setting:: web-securetlstransportexpiry + :displayname: Secure TLS transport expiry (Web Server) + :systemconsole: N/A + :configjson: .ServiceSettings.TLSStrictTransportMaxAge + :environment: MM_SERVICESETTINGS_TLSSTRICTTRANSPORTMAXAGE + :description: The time, in seconds, that the browser remembers a site is only to be accessed using HTTPS. Default is **63072000** seconds (2 years). + +Secure TLS transport expiry +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++--------------------------------------------------------+----------------------------------------------------------------------------------------+ +| The time, in seconds, that the browser remembers a | - System Config path: N/A | +| site is only to be accessed using HTTPS. After this | - ``config.json`` setting: ``".ServiceSettings.TLSStrictTransportMaxAge: 63072000",`` | +| period, a site can't be accessed using HTTP unless | - Environment variable: ``MM_SERVICESETTINGS_TLSSTRICTTRANSPORTMAXAGE`` | +| ``TLSStrictTransport`` is set to ``true``. | | +| | | +| Numerical input. Default is **63072000** (2 years). | | ++--------------------------------------------------------+----------------------------------------------------------------------------------------+ +| See the `Strict-Transport-Security `__ | +| documentation for details. | ++--------------------------------------------------------+----------------------------------------------------------------------------------------+ + +.. config:setting:: web-tlscipheroverwrites + :displayname: TLS cipher overwrites (Web Server) + :systemconsole: N/A + :configjson: .ServiceSettings.TLSOverwriteCiphers + :environment: MM_SERVICESETTINGS_TLSOVERWRITECIPHERS + :description: Set TLS ciphers overwrites to meet requirements from legacy clients which don't support modern ciphers, or to limit the types of accepted ciphers. + +TLS cipher overwrites +~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++--------------------------------------------------------+-----------------------------------------------------------------------------+ +| Set TLS ciphers overwrites to meet requirements from | - System Config path: N/A | +| legacy clients which don't support modern ciphers, | - ``config.json`` setting: ``".ServiceSettings.TLSOverwriteCiphers: []",`` | +| or to limit the types of accepted ciphers. | - Environment variable: ``MM_SERVICESETTINGS_TLSOVERWRITECIPHERS`` | +| | | +| If none specified, the Mattermost server assumes a | | +| set of currently considered secure ciphers, and allows | | +| overwrites in the edge case. | | +| | | +| String array input. | | ++--------------------------------------------------------+-----------------------------------------------------------------------------+ +| **Notes**: | +| | +| - This setting only takes effect if you are using the built-in server binary directly, and not using a reverse proxy layer, such | +| as NGINX. | +| - See the ``ServerTLSSupportedCiphers`` variable in `/model/config.go | +| `__ for a list of ciphers considered secure. | ++--------------------------------------------------------+-----------------------------------------------------------------------------+ + +.. config:setting:: web-goroutinehealththreshold + :displayname: Goroutine health threshold (Web Server) + :systemconsole: N/A + :configjson: .ServiceSettings.GoroutineHealthThreshold + :environment: MM_SERVICESETTINGS_GOROUTINEHEALTHTHRESHOLD + :description: Set a threshold on the number of goroutines when the Mattermost system is considered to be in a healthy state. Default is **-1** which turns off checking for the threshold. + +Goroutine health threshold +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++--------------------------------------------------------+----------------------------------------------------------------------------------+ +| Set a threshold on the number of goroutines when the | - System Config path: N/A | +| Mattermost system is considered to be in a healthy | - ``config.json`` setting: ``".ServiceSettings.GoroutineHealthThreshold: -1",`` | +| state. | - Environment variable: ``MM_SERVICESETTINGS_GOROUTINEHEALTHTHRESHOLD`` | +| | | +| When goroutines exceed this limit, a warning is | | +| returned in the server logs. | | +| | | +| Numeric input. Default is **-1** which turns off | | +| checking for the threshold. | | ++--------------------------------------------------------+----------------------------------------------------------------------------------+ + +.. config:setting:: web-allowcookiesforsubdomains + :displayname: Allow cookies for subdomains (Web Server) + :systemconsole: N/A + :configjson: .ServiceSettings.AllowCookiesForSubdomains + :environment: MM_SERVICESETTINGS_ALLOWCOOKIESFORSUBDOMAINS + + - **true**: **(Default)** Allows cookies for subdomains by setting the domain parameter on Mattermost cookies. + - **false**: Cookies not allowed for subdomains. + +Allow cookies for subdomains +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++--------------------------------------------------------+-------------------------------------------------------------------------------------+ +| - **true**: **(Default)** Allows cookies for | - System Config path: N/A | +| subdomains by setting the domain parameter on | - ``config.json`` setting: ``".ServiceSettings.AllowCookiesForSubdomains: true",`` | +| Mattermost cookies. | - Environment variable: ``MM_SERVICESETTINGS_ALLOWCOOKIESFORSUBDOMAINS`` | +| - **false**: Cookies not allowed for subdomains. | | ++--------------------------------------------------------+-------------------------------------------------------------------------------------+ + +.. config:setting:: web-clusterlogtimeout + :displayname: Cluster log timeout (Web Server) + :systemconsole: N/A + :configjson: .ServiceSettings.ClusterLogTimeoutMilliseconds + :environment: MM_SERVICESETTINGS_CLUSTERLOGTIMEOUTMILLISECONDS + :description: Define the frequency, in milliseconds, of cluster request time logging for performance monitoring. Default is **2000** milliseconds (2 seconds). + +Cluster log timeout +~~~~~~~~~~~~~~~~~~~ + +.. include:: ../_static/badges/ent-only.rst + :start-after: :nosearch: + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E20

+ ++--------------------------------------------------------+-----------------------------------------------------------------------------------------+ +| Define the frequency, in milliseconds, of cluster | - System Config path: N/A | +| request time logging for performance monitoring. | - ``config.json`` setting: ``".ServiceSettings.ClusterLogTimeoutMilliseconds: 2000",`` | +| | - Environment variable: ``MM_SERVICESETTINGS_CLUSTERLOGTIMEOUTMILLISECONDS`` | +| | | +| Numerical input. Default is **2000** milliseconds | | +| (2 seconds). | | ++--------------------------------------------------------+-----------------------------------------------------------------------------------------+ +| See the :doc:`performance monitoring ` documentation for details. | ++--------------------------------------------------------+-----------------------------------------------------------------------------------------+ + +.. config:setting:: service-maxpayloadsize + :displayname: Maximum payload size (File Storage) + :systemconsole: N/A + :configjson: .ServiceSettings.MaximumPayloadSizeBytes + :environment: MM_SERVICESETTINGS_MAXIMUMPAYLOADSIZEBYTES + :description: The maximum payload size in bytes for all APIs except APIs that receive a file as an input. For example, the upload attachment API or the API to upload a custom emoji. Default is 300000. + +Maximum payload size +~~~~~~~~~~~~~~~~~~~~ + ++-----------------------------------------------------------+-------------------------------------------------------------------------------------+ +| The maximum payload size in bytes for all APIs except | - System Config path: N/A | +| APIs that receive a file as an input. | - ``config.json`` setting: ``".ServiceSettings.MaximumPayloadSizeBytes: 300000",`` | +| | - Environment variable: ``MM_SERVICESETTINGS_MAXIMUMPAYLOADSIZEBYTES`` | +| For example, the upload attachment API or the API to | | +| upload a custom emoji. | | +| | | +| Numerical value. Default is **300000** (300 kB). | | ++-----------------------------------------------------------+-------------------------------------------------------------------------------------+ + +---- + +Database +-------- + +.. include:: ../_static/badges/allplans-selfhosted.rst + :start-after: :nosearch: + +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. + +.. include:: ../_static/badges/academy-mattermost-database.rst + :start-after: :nosearch: + +.. config:setting:: database-drivername + :displayname: Driver name (Database) + :systemconsole: N/A + :configjson: .SqlSettings.DriverName + :environment: MM_SQLSETTINGS_DRIVERNAME + :description: The type of database. Either **postgres** or **mysql**. The default value is **mysql**. + +Driver name +~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| The type of database. Can be either: | - System Config path: N/A | +| | - ``config.json`` setting: ``".SqlSettings.DriverName",`` | +| - **mysql**: **(Default)** Enables driver to MySQL database. | - Environment variable: ``MM_SQLSETTINGS_DRIVERNAME`` | +| - **postgres**: Enables driver to PostgreSQL database. | | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ + +.. config:setting:: database-datasource + :displayname: Data source (Database) + :systemconsole: N/A + :configjson: .SqlSettings.DataSource + :environment: MM_SQLSETTINGS_DATASOURCE + :description: The connection string to the master database. + +Data source +~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| The connection string to the master database. | - System Config path: N/A | +| | - ``config.json`` setting: ``".SqlSettings.DataSource",`` | +| String input. | - Environment variable: ``MM_SQLSETTINGS_DATASOURCE`` | +| | | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| **PostgreSQL databases** | +| | +| When **Driver Name** is set to ``postgres``, use a connection string in the form of: | +| ``postgres://mmuser:password@hostname_or_IP:5432/mattermost_test?sslmode=disable&connect_timeout=10`` | +| | +| **To use TLS with PostgreSQL databases** | +| | +| The parameter to encrypt connection against a PostgreSQL server is ``sslmode``. The library used to interact with PostgreSQL server is | +| `pq `__. Currently, it's not possible to use all the values that you could pass to a standard | +| PostgreSQL Client ``psql "sslmode=value"`` See the `SSL Mode Descriptions `__ | +| documentation for details. | +| | +| Your database admin must configure the functionality according to the supported values described below: | +| | +| +----------------------------------------+-----------------+---------------------------------------------------------------------------+ | +| | Short description of the ``sslmode`` | Value | Example of a data source name | | +| | parameter | | | | +| +========================================+=================+===========================================================================+ | +| | Don't use TLS / SSL encryption against | ``disable`` | ``postgres://mmuser:password@hostname_or_IP:5432/mattermost_test | | +| | the PostgreSQL server. | | ?sslmode=disable&connect_timeout=10`` | | +| | | | | | +| | Default value in file ``config.json`` | | | | +| +----------------------------------------+-----------------+---------------------------------------------------------------------------+ | +| | The data is encrypted and the network | ``require`` | ``postgres://mmuser:password@hostname_or_IP:5432/mattermost_test | | +| | is trusted. | | ?sslmode=require&connect_timeout=10`` | | +| | | | | | +| | Default value is ``sslmode`` when | | | | +| | omitted. | | | | +| +----------------------------------------+-----------------+---------------------------------------------------------------------------+ | +| | The data is encrypted when connecting | ``verify-ca`` | ``postgres://mmuser:password@hostname_or_IP:5432/mattermost_test | | +| | to a trusted server. | | ?sslmode=verify-ca&connect_timeout=10`` | | +| +----------------------------------------+-----------------+---------------------------------------------------------------------------+ | +| | The data is encrypted when connecting | ``verify-full`` | ``postgres://mmuser:password@hostname_or_IP:5432/mattermost_test | | +| | to a trusted server. | | ?sslmode=verify-full&connect_timeout=10`` | | +| +----------------------------------------+-----------------+---------------------------------------------------------------------------+ | +| | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| **MySQL databases** | +| | +| When **Driver Name** is set to ``mysql``, we recommend using ``collation`` over using ``charset``. | +| | +| To specify collation: | +| | +| .. code-block:: text | +| | +| "SqlSettings": { | +| "DataSource": | +| "@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: | +| | +| .. code-block:: text | +| | +| "SqlSettings": { | +| "DataSource": "@tcp(hostname or IP:3306)/mattermost?charset=utf8mb4,utf8", | +| [...] | +| } | +| | +| **Note**: If you’re using MySQL 8.0 or later, the default collation has changed to ``utf8mb4_0900_ai_ci``. See our | +| :doc:`Database Software Requirements ` documentation for details on MySQL 8.0 support. | +| | +| **To use TLS with MySQL databases** | +| | +| The parameter to encrypt connection against a MySQL server is ``tls``. | +| The library used to interact with MySQL is `Go-MySQL-Driver `__. | +| For the moment, it's not possible to use all the values that you could pass to a standard MySQL Client ``mysql --ssl-mode=value``. | +| See `Connection-Encryption Option Summary `__ | +| documentation for a version 8.0 example. | +| | +| Your database admin must configure the functionality according to supported values described below: | +| | +| +----------------------------------------+-----------------+---------------------------------------------------------------------------+ | +| | Short description of the ``tls`` | Value | Example of a data source name | | +| | parameter | | | | +| +========================================+=================+===========================================================================+ | +| | Don't use TLS / SSL encryption against | ``false`` | ``"@tcp(hostname or IP:3306)/mattermost_test | | +| | MySQL server. | | ?charset=utf8mb4,utf8&writeTimeout=30s&tls=false"`` | | +| +----------------------------------------+-----------------+---------------------------------------------------------------------------+ | +| | Use TLS / SSL encryption against | ``true`` | ``"@tcp(hostname or IP:3306)/mattermost_test | | +| | MySQL server. | | ?charset=utf8mb4,utf8&writeTimeout=30s&tls=true"`` | | +| +----------------------------------------+-----------------+---------------------------------------------------------------------------+ | +| | Use TLS / SSL encryption with a self- | ``skip-verify`` | ``"@tcp(hostname or IP:3306)/mattermost_test | | +| | signed certificate against | | ?charset=utf8mb4,utf8&writeTimeout=30s&tls=skip-verify"`` | | +| | MySQL server. | | | | +| +----------------------------------------+-----------------+---------------------------------------------------------------------------+ | +| | Use TLS / SSL encryption if server | ``preferred`` | ``"@tcp(hostname or IP:3306)/mattermost_test | | +| | advertises a possible fallback; | | ?charset=utf8mb4,utf8&writeTimeout=30s&tls=preferred"`` | | +| | unencrypted if it's not advertised. | | | | +| +----------------------------------------+-----------------+---------------------------------------------------------------------------+ | +| | ++------------------------------------------------------------+-----------------------------------------------------------------------------+ +| **AWS High Availablity RDS cluster deployments** | +| | +| For an AWS High Availability RDS cluster deployment, point this configuration setting to the write/read endpoint at the **cluster** | +| level to benefit from the AWS failover handling. AWS takes care of promoting different database nodes to be the writer node. | +| Mattermost doesn't need to manage this. See the | +| :ref:`high availablility database configuration ` documentation | +| for details. | ++------------------------------------------------------------+-----------------------------------------------------------------------------+ + +.. config:setting:: database-maxopenconnections + :displayname: Maximum open connections (Database) + :systemconsole: Environment > Database + :configjson: .SqlSettings.MaxOpenConns + :environment: MM_SQLSETTINGS_MAXOPENCONNS + :description: The maximum number of idle connections held open to the database. Default is **300**. + +Maximum open connections +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++--------------------------------------------------------+------------------------------------------------------------------+ +| The maximum number of open connections to the | - System Config path: **Environment > Database** | +| database. | - ``config.json`` setting: ``".SqlSettings.MaxOpenConns": 300,`` | +| | - Environment variable: ``MM_SQLSETTINGS_MAXOPENCONNS`` | +| Numerical input. Default is **300** for self-hosted | | +| deployments, and **100** for Cloud deployments. | | ++--------------------------------------------------------+------------------------------------------------------------------+ + +.. config:setting:: database-querytimeout + :displayname: Query timeout (Database) + :systemconsole: Environment > Database + :configjson: .SqlSettings.QueryTimeout + :environment: MM_SQLSETTINGS_QUERYTIMEOUT + :description: The amount of time to wait, in seconds, for a response from the database after opening a connection and sending the query. Default is **30** seconds. + +Query timeout +~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++--------------------------------------------------------+------------------------------------------------------------------+ +| The amount of time to wait, in seconds, for a response | - System Config path: **Environment > Database** | +| from the database after opening a connection and | - ``config.json`` setting: ``".SqlSettings.QueryTimeout: 30",`` | +| sending the query. | - Environment variable: ``MM_SQLSETTINGS_QUERYTIMEOUT`` | +| | | +| Numerical input in seconds. Default is **30** seconds. | | ++--------------------------------------------------------+------------------------------------------------------------------+ + +.. config:setting:: database-maxconnectionlifetime + :displayname: Maximum connection lifetime (Database) + :systemconsole: Environment > Database + :configjson: .SqlSettings.ConnMaxLifetimeMilliseconds + :environment: MM_SQLSETTINGS_CONNMAXLIFETIMEMILLISECONDS + :description: Maximum lifetime for a connection to the database, in milliseconds. Default is **3600000** milliseconds (1 hour). + +Maximum connection lifetime +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++--------------------------------------------------------+-------------------------------------------------------------------------------------+ +| Maximum lifetime for a connection to the database, | - System Config path: **Environment > Database** | +| in milliseconds. Use this setting to configure the | - ``config.json`` setting: ``".SqlSettings.ConnMaxLifetimeMilliseconds: 3600000",`` | +| maximum amount of time a connection to the database | - Environment variable: ``MM_SQLSETTINGS_CONNMAXLIFETIMEMILLISECONDS`` | +| may be reused | | +| | | +| Numerical input in milliseconds. Default is | | +| **3600000** milliseconds (1 hour). | | ++--------------------------------------------------------+-------------------------------------------------------------------------------------+ + +.. config:setting:: database-connmaxidletime + :displayname: Maximum connection idle timeout (Database) + :systemconsole: Environment > Database + :configjson: .SqlSettings.ConnMaxIdleTimeMilliseconds + :environment: MM_SQLSETTINGS_CONNMAXIDLETIMEMILLISECONDS + :description: Maximum time a database connection can remain idle, in milliseconds. Default is **300000** milliseconds (5 minutes). + +Maximum connection idle timeout +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++--------------------------------------------------------+-------------------------------------------------------------------------------------+ +| Maximum time a database connection can remain idle, | - System Config path: **Environment > Database** | +| in milliseconds. | - ``config.json`` setting: ``".SqlSettings.ConnMaxIdleTimeMilliseconds: 300000",`` | +| | - Environment variable: ``MM_SQLSETTINGS_CONNMAXIDLETIMEMILLISECONDS`` | +| Numerical input in milliseconds. Default is **300000** | | +| (5 minutes). | | ++--------------------------------------------------------+-------------------------------------------------------------------------------------+ + +.. config:setting:: database-minhashtaglength + :displayname: Minimum hashtag length (Database) + :systemconsole: Environment > Database + :configjson: .SqlSettings.MinimumHashtagLength + :environment: MM_SQLSETTINGS_MINIMUMHASHTAGLENGTH + :description: Minimum number of characters in a hashtag. This value must be greater than or equal to **2**. Default is **3**. + +Minimum hashtag length +~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++----------------------------------------------------------------------+-------------------------------------------------------------------------+ +| Minimum number of characters in a hashtag. | - System Config path: **Environment > Database** | +| This value must be greater than or equal to **2**. | - ``config.json`` setting: ``".SqlSettings.MinimumHashtagLength: 3",`` | +| | - Environment variable: ``MM_SQLSETTINGS_MINIMUMHASHTAGLENGTH`` | ++----------------------------------------------------------------------+-------------------------------------------------------------------------+ +| **Note**: MySQL databases must be configured to support searching strings shorter than three characters. See the | +| `MySQL documentation `__ for details. | ++----------------------------------------------------------------------+-------------------------------------------------------------------------+ + +.. config:setting:: database-sqltrace + :displayname: SQL statement logging (Database) + :systemconsole: Environment > Database + :configjson: .SqlSettings.Trace + :environment: MM_SQLSETTINGS_TRACE + + - **true**: Executing SQL statements are written to the log. + - **false**: **(Default)** SQL statements aren't written to the log. + +SQL statement logging +~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| Executed SQL statements can be written to the log for | - System Config path: **Environment > Database** | +| development. | - ``config.json`` setting: ``".SqlSettings.Trace: false",`` | +| | - Environment variable: ``MM_SQLSETTINGS_TRACE`` | +| - **true**: Executing SQL statements are written to the log. | | +| - **false**: **(Default)** SQL statements aren't written | | +| to the log. | | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ + +Recycle database connections +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: ../_static/badges/ent-only.rst + :start-after: :nosearch: + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E20

+ ++--------------------------------------------------------+------------------------------------------------------------------+ +| Select the **Recycle Database Connections** button to | - System Config path: **Environment > Database** | +| manually recycle the connection pool by closing the | - ``config.json`` setting: N/A | +| current set of open connections to the database | - Environment variable: N/A | +| within 20 seconds, and then creating a new set of | | +| connections. | | +| | | +| To fail over without stopping the server, change the | | +| database line in the ``config.json`` file, select | | +| **Reload Configuration from Disk** via **Environment | | +| > Web Server**, then select **Recycle Database | | +| Connections**. | | ++--------------------------------------------------------+------------------------------------------------------------------+ + +.. config:setting:: database-disablesearch + :displayname: Disable database search (Database) + :systemconsole: Environment > Database + :configjson: .SqlSettings.DisableDatabaseSearch + :environment: MM_SQLSETTINGS_DISABLEDATABASESEARCH + + - **true**: Disables the use of the database to perform searches. If another search engine isn't configured, setting this value to ``true`` will result in empty search results. + - **false**: **(Default)** Database search isn't disabled. + +Disable database search +~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+------------------------------------------------------------------------------+ +| When other search engines are configured, such as | - System Config path: **Environment > Database** | +| :doc:`Elasticsearch `, | - ``config.json`` setting: ``".SqlSettings.DisableDatabaseSearch: false",`` | +| the database can be disabled to perform searches. | - Environment variable: ``MM_SQLSETTINGS_DISABLEDATABASESEARCH`` | +| | | +| - **true**: Disables the use of the database to perform | | +| searches. If another search engine isn't configured, | | +| setting this value to ``true`` will result in empty search | | +| results. | | +| - **false**: **(Default)** Database search isn't disabled. | | ++---------------------------------------------------------------+------------------------------------------------------------------------------+ +| Search behavior in Mattermost depends on which search engines are enabled. | +| | +| - When :doc:`Elasticsearch ` is enabled, Mattermost will try to use it first. | +| - If Elasticsearch fails or is disabled, Mattermost will attempt to use :doc:`Bleve `, if enabled. If this occurs, | +| you will see the warning ``Encountered error on SearchPostsInTeamForUser.`` | +| - If both Elasticsearch and Bleve fail or are disabled, Mattermost tries to search the database directly, if this is enabled. | +| - If all of the above methods fail or are disabled, the search results will be empty. | ++---------------------------------------------------------------+------------------------------------------------------------------------------+ + +Applied schema migrations +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ +A list of all migrations that have been applied to the data store based on the version information available in the ``db_migrations`` table. Select **About Mattermost** from the product menu to review the current database schema version applied to your deployment. + + +.. config:setting:: database-activesearchbackend + :displayname: Active search backend (Database) + :systemconsole: Environment > Database + :configjson: N/A + :environment: N/A + :description: Read-only display of the currently active backend used for search. + +Active Search Backend +~~~~~~~~~~~~~~~~~~~~~ + +Read-only display of the currently active backend used for search. Values can include ``none``, ``database``, ``elasticsearch``, or ``bleve``. + +.. config:setting:: database-readreplicas + :displayname: Read replicas (Database) + :systemconsole: N/A + :configjson: .SqlSettings.DataSourceReplicas + :environment: MM_SQLSETTINGS_DATASOURCEREPLICAS + :description: Specifies the connection strings for the read replica databases. + +Read replicas +~~~~~~~~~~~~~ + +.. include:: ../_static/badges/ent-pro-only.rst + :start-after: :nosearch: + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++--------------------------------------------------------+-----------------------------------------------------------------------+ +| Specifies the connection strings for the read replica | - System Config path: N/A | +| databases. | - ``config.json`` setting: ``".SqlSettings.DataSourceReplicas": []`` | +| | - Environment variable: ``MM_SQLSETTINGS_DATASOURCEREPLICAS`` | ++--------------------------------------------------------+-----------------------------------------------------------------------+ +| **Note**: Each database connection string in the array must be in the same form used for the | +| `Data source <#data-source>`__ setting. | ++--------------------------------------------------------+-----------------------------------------------------------------------+ +| **AWS High Availablity RDS cluster deployments** | +| | +| For an AWS High Availability RDS cluster deployment, point this configuration setting directly to the underlying read-only | +| node endpoint within the RDS cluster to circumvent the failover/load balancing that AWS/RDS takes care of (except for the | +| write traffic). Mattermost has its own method of balancing the read-only connections, and can also balance those queries to | +| the data source/write+read connection should those nodes fail. See the | +| :ref:`high availablility database configuration ` | +| documentation for details. | ++--------------------------------------------------------+-----------------------------------------------------------------------+ + +.. config:setting:: database-searchreplicas + :displayname: Search replicas (Database) + :systemconsole: N/A + :configjson: .SqlSettings.DataSourceSearchReplicas + :environment: MM_SQLSETTINGS_DATASOURCESEARCHREPLICAS + + Specifies the connection strings for the search replica databases. + A search replica is similar to a read replica, but is used only for handling search queries. + +Search replicas +~~~~~~~~~~~~~~~ + +.. include:: ../_static/badges/ent-pro-only.rst + :start-after: :nosearch: + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++--------------------------------------------------------+-----------------------------------------------------------------------------+ +| Specifies the connection strings for the search | - System Config path: N/A | +| replica databases. A search replica is similar to a | - ``config.json`` setting: ``".SqlSettings.DataSourceSearchReplicas": []`` | +| read replica, but is used only for handling search | - Environment variable: ``MM_SQLSETTINGS_DATASOURCESEARCHREPLICAS`` | +| queries. | | ++--------------------------------------------------------+-----------------------------------------------------------------------------+ +| **Note**: Each database connection string in the array must be in the same form used for the `Data source <#data-source>`__ | +| setting. | ++--------------------------------------------------------+-----------------------------------------------------------------------------+ +| **AWS High Availablity RDS cluster deployments** | +| | +| For an AWS High Availability RDS cluster deployment, point this configuration setting directly to the underlying read-only | +| node endpoint within the RDS cluster to circumvent the failover/load balancing that AWS/RDS takes care of (except for the | +| write traffic). Mattermost has its own method of balancing the read-only connections, and can also balance those queries to | +| the data source/write+read connection should those nodes fail. See the | +| :ref:`high availablility database configuration ` | +| documentation for details. | ++--------------------------------------------------------+-----------------------------------------------------------------------------+ + +.. config:setting:: database-replicalagsettings + :displayname: Replica lag settings (Database) + :systemconsole: N/A + :configjson: .SqlSettings.ReplicaLagSettings + :environment: MM_SQLSETTINGS_REPLICALAGSETTINGS + :description: Specifies a connection string and user-defined SQL queries on the database to measure replica lag for a single replica instance. + +Replica lag settings +~~~~~~~~~~~~~~~~~~~~ + +.. include:: ../_static/badges/ent-only.rst + :start-after: :nosearch: + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E20

+ ++--------------------------------------------------------+----------------------------------------------------------------------------------+ +| String array input specifies a connection string and | - System Config path: N/A | +| user-defined SQL queries on the database to measure | - ``config.json`` setting: ``".SqlSettings.ReplicaLagSettings": []`` | +| replica lag for a single replica instance. | - Environment variable: ``MM_SQLSETTINGS_REPLICALAGSETTINGS`` | +| | | +| These settings monitor absolute lag based on binlog | | +| distance/transaction queue length, and the time taken | | +| for the replica to catch up. | | +| | | +| String array input consists of: | | +| | | +| - ``DataSource``: The database credentials to connect | | +| to the database instance. | | +| - ``QueryAbsoluteLag``: A plain SQL query that must | | +| return a single row. The first column must be the | | +| node value of the Prometheus metric, and the second | | +| column must be the value of the lag used to | | +| measure absolute lag. | | +| - ``QueryTimeLag``: A plain SQL query that must | | +| return a single row. The first column must be the | | +| node value of the Prometheus metric, and the second | | +| column must be the value of the lag used to measure | | +| the time lag. | | ++--------------------------------------------------------+----------------------------------------------------------------------------------+ +| **Notes**: | +| | +| - The ``QueryAbsoluteLag`` and ``QueryTimeLag`` queries must return a single row. | +| - To properly monitor this, you must setup :doc:`performance monitoring ` | +| for Mattermost. | ++--------------------------------------------------------+----------------------------------------------------------------------------------+ + +1. Configure the replica lag metric based on your database type. See the following tabs for details on configuring this for each database type. + + .. tab:: AWS Aurora + + Add the configuration highlighted below to your ``SqlSettings.ReplicaLagSettings`` array. You only need to add this once because replication statistics for AWS Aurora nodes are visible across all server instances that are members of the cluster. Be sure to change the ``DataSource`` to point to a single node in the group. + + For more information on Aurora replication stats, see the `AWS Aurora documentaion `__. + + **Example:** + + .. code-block:: json + :emphasize-lines: 4,5,6,7,8 + + { + "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=<>" + } + ] + } + } + + .. tab:: MySQL Group Replication + + Add the configuration highlighted below to your ``SqlSettings.ReplicaLagSettings`` array. You only need to add this once because replication statistics for all nodes are shared across all server instances that are members of the MySQL replication group. Be sure to change the ``DataSource`` to point to a single node in the group. + + For more information on group replication stats, see the `MySQL documentation `__. + + **Example:** + + .. code-block:: json + :emphasize-lines: 4,5,6,7,8 + + { + "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": "" + } + ] + } + } + + .. tab:: PostgreSQL replication slots + + 1. Add the configuration highlighted below to your ``SqlSettings.ReplicaLagSettings`` array. This query should run against the **primary** node in your cluster, to do this change the ``DataSource`` to match the `SqlSettings.DataSource <#data-source>`__ setting you have configured. + + For more information on pg_stat_replication, see the `PostgreSQL documentation `__. + + **Example:** + + .. code-block:: json + :emphasize-lines: 4,5,6,7,8 + + { + "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": "" + } + ] + } + } + + 2. Grant permissions to the database user for ``pg_monitor``. This user should be the same user configured above in the ``DataSource`` string. + + For more information on roles, see the `PostgreSQL documentation `__. + + .. code-block:: sh + + sudo -u postgres psql + postgres=# GRANT pg_monitor TO mmuser; + +2. Save the config and restart all Mattermost nodes. +3. Navigate to your Grafana instance monitoring Mattermost and open the `Mattermost Performance Monitoring v2 `__ dashboard. +4. The ``QueryTimeLag`` chart is already setup for you utilizing the existing ``Replica Lag`` chart. If using ``QueryAbsoluteLag`` metric clone the ``Replica Lag`` chart and edit the query to use the below absolute lag metrics and modify the title to be ``Replica Lag Absolute``. + + .. code-block:: text + + mattermost_db_replica_lag_abs{instance=~"$server"} + + .. image:: ../../source/images/database-configuration-settings-replica-lag-grafana-1.jpg + :alt: A screenshot showing how to clone a chart within Grafana + + + .. image:: ../../source/images/database-configuration-settings-replica-lag-grafana-2.jpg + :alt: A screenshot showing the specific edits to make to the cloned grafana chart. + + +.. config:setting:: database-replicamonitorintervalseconds + :displayname: Replica monitor interval (Database) + :systemconsole: N/A + :configjson: .SqlSettings.ReplicaMonitorIntervalSeconds + :environment: MM_SQLSETTINGS_REPLICAMONITORINTERVALSECONDS + + Specifies how frequently unhealthy replicas will be monitored for liveness check. Mattermost will dynamically choose a replica if it's alive. + +Replica monitor interval (seconds) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: ../_static/badges/allplans-selfhosted.rst + :start-after: :nosearch: + ++--------------------------------------------------------+---------------------------------------------------------------------------------+ +| Specifies how frequently unhealthy replicas will be | - System Config path: N/A | +| monitored for liveness check. Mattermost will | - ``config.json`` setting: ``".SqlSettings.ReplicaMonitorIntervalSeconds": 5`` | +| dynamically choose a replica if it's alive. | - Environment variable: ``MM_SQLSETTINGS_REPLICAMONITORINTERVALSECONDS`` | +| | | +| Numerical input. Default is 5 seconds. | | ++--------------------------------------------------------+---------------------------------------------------------------------------------+ + +---- + +Elasticsearch +------------- + +.. include:: ../_static/badges/ent-selfhosted.rst + :start-after: :nosearch: + +Elasticsearch provides enterprise-scale deployments with optimized search performance and prevents performance degradation and timeouts. Learn more about :doc:`Elasticsearch ` in our product documentation. + +You can configure the Elasticsearch environment in which Mattermost is deployed in **System Console > Environment > Elasticsearch**. You can also edit the ``config.json`` file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect. + +.. config:setting:: elastic-enableindexing + :displayname: Enable Elasticsearch indexing (Elasticsearch) + :systemconsole: Environment > Elasticsearch + :configjson: .Elasticsearchsettings.EnableIndexing + :environment: MM_ELASTICSEARCHSETTINGS_ENABLEINDEXING + :description: Configure Mattermost to index new posts automatically. + + - **true**: Indexing of new posts occurs automatically. + - **false**: **(Default)** Elasticsearch indexing is disabled and new messages aren't indexed. + +Enable Elasticsearch indexing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+--------------------------------------------------------------------------------+ +| Configure Mattermost to index new posts automatically. | - System Config path: **Environment > Elasticsearch** | +| | - ``config.json`` setting: ``".Elasticsearchsettings.EnableIndexing: false",`` | +| - **true**: Indexing of new messages occurs automatically. | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_ENABLEINDEXING`` | +| - **false**: **(Default)** Elasticsearch indexing is disabled | | +| and new messages aren't indexed. | | ++---------------------------------------------------------------+--------------------------------------------------------------------------------+ +| **Notes**: | +| | +| - Core search happens in a relational database and is intended for deployments under about 2-3 million posts and file entries. Beyond that | +| scale, `enabling Elasticsearch for search queries <#enable-elasticsearch-for-search-queries>`__ is highly recommended | +| - If you anticipate your Mattermost server reaching more than 2.5 million posts and file entries, we recommend enabling Elasticsearch for | +| optimum search performance **before** reaching 3 million posts. | +| - For deployments with over 3 million posts, Elasticsearch is required to avoid significant performance issues, such as timeouts, with | +| :doc:`message searches ` and :doc:`@mentions `. | +| - If indexing is disabled and then re-enabled after an index is created, purge and rebuild the index to ensure complete search results. | ++---------------------------------------------------------------+--------------------------------------------------------------------------------+ + +.. config:setting:: elastic-backendtype + :displayname: Elasticsearch backend type (Elasticsearch) + :systemconsole: Environment > Elasticsearch + :configjson: .Elasticsearchsettings.Backend + :environment: MM_ELASTICSEARCHSETTINGS_BACKEND + :description: Set the type of search backend as either Elasticsearch or Opensearch. + +Backend type +~~~~~~~~~~~~~ + ++----------------------------------------------------+-----------------------------------------------------------------------------------+ +| The type of search backend. | - System Config path: **Environment > Elasticsearch** | +| | - ``config.json`` setting: ``".Elasticsearchsettings.Backend: elasticsearch",`` | +| - ``elasticsearch`` - (**Default**) | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_BACKEND`` | +| - ``opensearch`` - Required for AWS Opensearch | | +| customers. | | ++----------------------------------------------------+-----------------------------------------------------------------------------------+ + +.. important:: + + Mattermost v9.11 introduces support for `Elasticsearch v8 `__ and beta support for `Opensearch v1.x and v2.x `_. + + - Mattermost supports Elasticsearch v7.17+. However, we recommend upgrading your Elasticsearch v7 instance to v8.x. See the `Elasticsearch upgrade `_ documentation for details. + - Customers using Elasticsearch v8 must set ``action.destructive_requires_name`` to ``false`` in ``elasticsearch.yml`` to enable wildcard operations. + + **AWS Elasticsearch Customers** + + The official AWS Elasticsearch v8 client only works from Elasticsearch v7.11 and later. This is a breaking change for customers using AWS Elasticsearch v7.10.x. If you're using AWS Elasticsearch, you must upgrade to `AWS Opensearch `_. See the `AWS Amazon Opensearch upgrade `_ documentation for details. + + If you're using AWS Elasticsearch, you must: + + 1. Upgrade to AWS Opensearch for future compatibility. Refer to the `Opensearch upgrade `_ documentation for details. + 2. Disable "compatibility mode" in Opensearch. + 3. Upgrade the Mattermost server. + 4. Change the default ``ElasticsearchSettings.Backend`` configuration value from ``elasticsearch`` to ``opensearch`` using :ref:`mmctl config set `, or by editing the ``config.json`` file manually. This value cannot be changed using the System Console. See the Mattermost :ref:`Elasticsearch backend type ` documentation for additional details. + 5. Restart the Mattermost server. + +.. config:setting:: elastic-serverconnectionaddress + :displayname: Server connection address (Elasticsearch) + :systemconsole: Environment > Elasticsearch + :configjson: .Elasticsearchsettings.ConnectionUrl + :environment: MM_ELASTICSEARCHSETTINGS_CONNECTIONURL + :description: The address of the Elasticsearch server. + +Server connection address +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++----------------------------------------------------+--------------------------------------------------------------------------+ +| The address of the Elasticsearch server. | - System Config path: **Environment > Elasticsearch** | +| | - ``config.json`` setting: ``".Elasticsearchsettings.ConnectionUrl",`` | +| | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_CONNECTIONURL`` | ++----------------------------------------------------+--------------------------------------------------------------------------+ + +.. config:setting:: elastic-CApath + :displayname: CA path (Elasticsearch) + :systemconsole: Environment > Elasticsearch + :configjson: .Elasticsearchsettings.CA + :environment: MM_ELASTICSEARCHSETTINGS_CA + :description: Optional path to the Custom Certificate Authority certificates for the Elasticsearch server. + +CA path +~~~~~~~ + ++----------------------------------------------------+--------------------------------------------------------------------------+ +| Optional path to the Custom Certificate Authority | - System Config path: **Environment > Elasticsearch** | +| certificates for the Elasticsearch server. | - ``config.json`` setting: ``".Elasticsearchsettings.CA",`` | +| | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_CA`` | ++----------------------------------------------------+--------------------------------------------------------------------------+ +| **Note**: Available from Mattermost v7.8. Can be used in conjunction with basic auth credentials or to replace them. | +| Leave this setting blank to use the default Certificate Authority certificates for the operating system. | ++----------------------------------------------------+--------------------------------------------------------------------------+ + +.. config:setting:: elastic-clientcertificatepath + :displayname: Client certificate path (Elasticsearch) + :systemconsole: Environment > Elasticsearch + :configjson: .Elasticsearchsettings.ClientCert + :environment: MM_ELASTICSEARCHSETTINGS_CLIENTCERT + :description: Optional client certificate for the connection to the Elasticsearch server in PEM format. + +Client certificate path +~~~~~~~~~~~~~~~~~~~~~~~ + ++----------------------------------------------------+--------------------------------------------------------------------------+ +| Optional client certificate for the connection to | - System Config path: **Environment > Elasticsearch** | +| the Elasticsearch server in the PEM format. | - ``config.json`` setting: ``".Elasticsearchsettings.ClientCert",`` | +| | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_CLIENTCERT`` | ++----------------------------------------------------+--------------------------------------------------------------------------+ +| **Note**: Available from Mattermost v7.8. Can be used in conjunction with basic auth credentials or to replace them. | ++----------------------------------------------------+--------------------------------------------------------------------------+ + +.. config:setting:: elastic-clientcertificatekeypath + :displayname: Client certificate key path (Elasticsearch) + :systemconsole: Environment > Elasticsearch + :configjson: .Elasticsearchsettings.ClientKey + :environment: MM_ELASTICSEARCHSETTINGS_CLIENTKEY + :description: Optional key for the client certificate in PEM format. + +Client certificate key path +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++----------------------------------------------------+--------------------------------------------------------------------------+ +| Optional key for the client certificate in the PEM | - System Config path: **Environment > Elasticsearch** | +| format. | - ``config.json`` setting: ``".Elasticsearchsettings.ClientKey",`` | +| | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_CLIENTKEY`` | ++----------------------------------------------------+--------------------------------------------------------------------------+ +| **Note**: Available from Mattermost v7.8. Can be used in conjunction with basic auth credentials or to replace them. | ++----------------------------------------------------+--------------------------------------------------------------------------+ + +.. config:setting:: elastic-skiptlsverification + :displayname: Skip TLS verification (Elasticsearch) + :systemconsole: Environment > Elasticsearch + :configjson: .Elasticsearchsettings.SkipTLSVerification + :environment: MM_ELASTICSEARCHSETTINGS_SKIPTLSVERIFICATION + :description: The certificate step for TLS connections can be skipped. + + - **true**: Skips the certificate verification step for TLS connections. + - **false**: **(Default)** Mattermost does not skip certificate verification. + +Skip TLS verification +~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+-------------------------------------------------------------------------------------+ +| The certificate step for TLS connections can be skipped. | - System Config path: **Environment > Elasticsearch** | +| | - ``config.json`` setting: ``".Elasticsearchsettings.SkipTLSVerification: false",`` | +| - **true**: Skips the certificate verification step for | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_SKIPTLSVERIFICATION`` | +| TLS connections. | | +| - **false**: **(Default)** Mattermost does not skip | | +| certificate verification. | | ++---------------------------------------------------------------+-------------------------------------------------------------------------------------+ + +.. config:setting:: elastic-serverusername + :displayname: Server username (Elasticsearch) + :systemconsole: Environment > Elasticsearch + :configjson: .Elasticsearchsettings.UserName + :environment: MM_ELASTICSEARCHSETTINGS_USERNAME + :description: (Optional) The username to authenticate to the Elasticsearch server. + +Server username +~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| (Optional) The username to authenticate to the | - System Config path: **Environment > Elasticsearch** | +| Elasticsearch server. | - ``config.json`` setting: ``".Elasticsearchsettings.UserName",`` | +| | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_USERNAME`` | +| String input. | | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ + +.. config:setting:: elastic-serverpassword + :displayname: Server password (Elasticsearch) + :systemconsole: Environment > Elasticsearch + :configjson: .Elasticsearchsettings.Password + :environment: MM_ELASTICSEARCHSETTINGS_PASSWORD + :description: (Optional) The password to authenticate to the Elasticsearch server. + +Server password +~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| (Optional) The password to authenticate to the | - System Config path: **Environment > Elasticsearch** | +| Elasticsearch server. | - ``config.json`` setting: ``".Elasticsearchsettings.Password",`` | +| | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_PASSWORD`` | +| String input. | | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ + +.. config:setting:: elastic-enablesniffing + :displayname: Enable cluster sniffing (Elasticsearch) + :systemconsole: Environment > Elasticsearch + :configjson: .Elasticsearchsettings.Sniff + :environment: MM_ELASTICSEARCHSETTINGS_SNIFF + :description: Configure Mattermost to automatically find and connect to all data nodes in a cluster. + + - **true**: Sniffing finds and connects to all data nodes in your cluster automatically. + - **false**: **(Default)** Cluster sniffing is disabled. + +Enable cluster sniffing +~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++----------------------------------------------------------------+--------------------------------------------------------------------------+ +| Configure Mattermost to automatically find and connect to | - System Config path: **Environment > Elasticsearch** | +| all data nodes in a cluster. | - ``config.json`` setting: ``".Elasticsearchsettings.Sniff: false",`` | +| | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_SNIFF`` | +| - **true**: Sniffing finds and connects to all data nodes | | +| in your cluster automatically. | | +| - **false**: **(Default)** Cluster sniffing is disabled. | | ++----------------------------------------------------------------+--------------------------------------------------------------------------+ +| Select the **Test Connection** button in the System Console to validate the connection between Mattermost and the Elasticsearch server. | ++----------------------------------------------------------------+--------------------------------------------------------------------------+ + +.. config:setting:: elastic-bulkindexing + :displayname: Bulk indexing (Elasticsearch) + :systemconsole: Environment > Elasticsearch + :configjson: N/A + :environment: N/A + :description: Configure Mattermost to start a bulk index of all existing posts in the database by selecting Index Now. + +Bulk indexing +~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| Configure Mattermost to start a bulk index of all existing | - System Config path: **Environment > Elasticsearch** | +| posts in the database, from oldest to newest. | - ``config.json`` setting: N/A | +| | - Environment variable: N/A | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| **Notes**: | +| | +| - Always `purge indexes <#purge-indexes>`__ before bulk indexing. | +| - Select the **Index Now** button in the System Console to start a bulk index of all posts, and review all index jobs in progress. | +| - Elasticsearch is available during indexing, but search results may be incomplete until the indexing job is complete. | +| - If an in-progress indexing job is canceled, the index and search results will be incomplete. | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ + +.. config:setting:: elastic-rebuildchannelsindex + :displayname: Rebuild channels index (Elasticsearch) + :systemconsole: Environment > Elasticsearch + :configjson: N/A + :environment: N/A + :description: Purge the channels index adn re-index all channels in the database, from oldest to newest. + +Rebuild channels index +~~~~~~~~~~~~~~~~~~~~~~ + ++---------------------------------------------------------------+---------------------------------------------------------------+ +| Purge the channels index adn re-index all channels in the | - System Config path: **Environment > Elasticsearch** | +| database, from oldest to newest. | - ``config.json`` setting: N/A | +| | - Environment variable: N/A | ++---------------------------------------------------------------+---------------------------------------------------------------+ +| Select the **Rebuild Channels Index** button in the System Console to purge the channels index. | +| Ensure no other indexing jobs are in progress via the **Bulk Indexing** table before starting this process. | +| During indexing, channel auto-complete is available, but search results may be incomplete until the indexing job is complete. | ++---------------------------------------------------------------+---------------------------------------------------------------+ + +.. config:setting:: elastic-purgeindexes + :displayname: Purge indexes (Elasticsearch) + :systemconsole: Environment > Elasticsearch + :configjson: N/A + :environment: N/A + :description: Purge the entire Elasticsearch index by selecting Purge Indexes before creating a new index. + +Purge indexes +~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++-------------------------------------------+-------------------------------------------------------------+ +| Purge the entire Elasticsearch index. | - System Config path: **Environment > Elasticsearch** | +| | - ``config.json`` setting: N/A | +| | - Environment variable: N/A | ++-------------------------------------------+-------------------------------------------------------------+ +| Select the **Purge Indexes** button in the System Console to purge the index. | +| After purging the index, create a new index by selecting the **Index Now** button. | ++-------------------------------------------+-------------------------------------------------------------+ + +.. config:setting:: elastic-indexestoskipwhilepurging + :displayname: Indexes to skip while purging (Elasticsearch) + :systemconsole: Environment > Elasticsearch + :configjson: .Elasticsearchsettings.IgnoredPurgeIndexes + :environment: MM_ELASTICSEARCHSETTINGS_IGNOREDPURGEINDEXES + :description: Specify index names to ignore while purging indexes, separated by commas. + +Indexes to skip while purging +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++---------------------------------------------------------------+---------------------------------------------------------------------------+ +| Specify index names to ignore while purging indexes. | - System Config path: **Environment > Elasticsearch** | +| Separate multiple index names with commas. | - ``config.json`` setting: ``ElasticsearchSettings.IgnoredPurgeIndexes`` | +| | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_IGNOREDPURGEINDEXES`` | +| Use an asterisk (*) to match a sequence of index name | | +| characters. | | ++---------------------------------------------------------------+---------------------------------------------------------------------------+ + +.. config:setting:: elastic-enablesearch + :displayname: Enable Elasticsearch for search queries (Elasticsearch) + :systemconsole: Environment > Elasticsearch + :configjson: .Elasticsearchsettings.EnableSearching + :environment: MM_ELASTICSEARCHSETTINGS_ENABLESEARCHING + :description: Configure Mattermost to use Elasticsearch for all search queries using the latest index. + + - **true**: Elasticsearch is used for all search queries using the latest index. Search results may be incomplete until a bulk index of the existing message database is completed. + - **false**: **(Default)** Relational database search is used for search queries. + +Enable Elasticsearch for search queries +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ +.. important:: + + - Core search happens in a relational database and is intended for deployments under about 2-3 million posts and file entries. Beyond that scale, enabling Elasticsearch for search queries is highly recommended. + - If you anticipate your Mattermost server reaching more than 2.5 million posts and file entries, we recommend enabling Elasticsearch for optimum search performance **before** reaching 3 million posts. + - For deployments with over 3 million posts, Elasticsearch with :ref:`dedicated indexing ` and scaled usage resourcing through :doc:`cluster support ` is required to avoid significant performance issues, such as timeouts, with :doc:`message searches ` and :doc:`@mentions `. + ++---------------------------------------------------------------+---------------------------------------------------------------------------------+ +| Configure Mattermost to use Elasticsearch for all search | - System Config path: **Environment > Elasticsearch** | +| queries using the latest index. | - ``config.json`` setting: ``".Elasticsearchsettings.EnableSearching: false",`` | +| | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_ENABLESEARCHING`` | +| - **true**: Elasticsearch is used for all search queries | | +| using the latest index. Search results may be incomplete | | +| until a bulk index of the existing message database is | | +| completed. | | +| - **false**: **(Default)** Database search is used for | | +| search queries. | | ++---------------------------------------------------------------+---------------------------------------------------------------------------------+ +| **Note**: If indexing is disabled and then re-enabled after an index is created, purge and rebuild the index to ensure complete search results. | ++---------------------------------------------------------------+---------------------------------------------------------------------------------+ + +.. config:setting:: elastic-enableautocomplete + :displayname: Enable Elasticsearch for autocomplete queries (Elasticsearch) + :systemconsole: Environment > Elasticsearch + :configjson: .Elasticsearchsettings.EnableAutocomplete + :environment: MM_ELASTICSEARCHSETTINGS_ENABLEAUTOCOMPLETE + :description: Configure Mattermost to use Elasticsearch for all autocompletion queries on users and channels using the latest index. + + - **true**: Elasticsearch will be used for all autocompletion queries on users and channels using the latest index. + - **false**: **(Default)** Database autocomplete is used. + +Enable Elasticsearch for autocomplete queries +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+------------------------------------------------------------------------------------+ +| Configure Mattermost to use Elasticsearch for all | - System Config path: **Environment > Elasticsearch** | +| autocompletion queries on users and channels using the | - ``config.json`` setting: ``".Elasticsearchsettings.EnableAutocomplete: false",`` | +| latest index. | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_ENABLEAUTOCOMPLETE`` | +| | | +| - **true**: Elasticsearch will be used for all autocompletion | | +| queries on users and channels using the latest index. | | +| - **false**: **(Default)** Database autocomplete is used. | | ++---------------------------------------------------------------+------------------------------------------------------------------------------------+ +| **Note**: Autocompletion results may be incomplete until a bulk index of the existing users and channels database is finished. | ++---------------------------------------------------------------+------------------------------------------------------------------------------------+ + +.. config:setting:: elastic-postindexreplicas + :displayname: Post index replicas (Elasticsearch) + :systemconsole: N/A + :configjson: .Elasticsearchsettings.PostIndexReplicas + :environment: MM_ELASTICSEARCHSETTINGS_POSTINDEXREPLICAS + :description: The number of replicas to use for each post index. Default is **1**. + +Post index replicas +~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+-------------------------------------------------------------------------------+ +| The number of replicas to use for each post index. | - System Config path: N/A | +| | - ``config.json`` setting: ``".Elasticsearchsettings.PostIndexReplicas: 1",`` | +| Numerical input. Default is **1**. | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_POSTINDEXREPLICAS`` | ++---------------------------------------------------------------+-------------------------------------------------------------------------------+ +| **Important notes**: | +| | +| - If this setting is changed, the changed configuration only applies to newly-created indexes. To apply the change to existing indexes, | +| purge and rebuild the index after changing this setting. | +| - If there are ``n`` data nodes, the number of replicas per shard for each index should be ``n-1``. | +| - If the number of nodes in an Elasticsearch cluster changes, this configuration setting, as well as | +| `Channel Index Replicas <#channel-index-replicas>`__ and `User Index Replicas <#user-index-replicas>`__ must also be updated accordingly. | ++---------------------------------------------------------------+-------------------------------------------------------------------------------+ + +.. config:setting:: elastic-postindexshards + :displayname: Post index shards (Elasticsearch) + :systemconsole: N/A + :configjson: .Elasticsearchsettings.PostIndexShards + :environment: MM_ELASTICSEARCHSETTINGS_POSTINDEXSHARDS + :description: The number of shards to use for each post index. Default is **1**. + +Post index shards +~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+-------------------------------------------------------------------------------+ +| The number of shards to use for each post index. | - System Config path: N/A | +| | - ``config.json`` setting: ``".Elasticsearchsettings.PostIndexShards: 1",`` | +| Numerical input. Default is **1**. | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_POSTINDEXSHARDS`` | ++---------------------------------------------------------------+-------------------------------------------------------------------------------+ +| **Important note**: If this configuration setting is changed, the changed configuration only applies to newly-created indexes. | +| To apply the change to existing indexes, purge and rebuild the index after changing this setting. | ++---------------------------------------------------------------+-------------------------------------------------------------------------------+ + + +.. config:setting:: elastic-channelindexreplicas + :displayname: Channel index replicas (Elasticsearch) + :systemconsole: N/A + :configjson: .Elasticsearchsettings.ChannelIndexReplicas + :environment: MM_ELASTICSEARCHSETTINGS_CHANNELINDEXREPLICAS + :description: The number of replicas to use for each channel index. Default is **1**. + +Channel index replicas +~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+----------------------------------------------------------------------------------+ +| The number of replicas to use for each channel index. | - System Config path: N/A | +| | - ``config.json`` setting: ``".Elasticsearchsettings.ChannelIndexReplicas: 1",`` | +| Numerical input. Default is **1**. | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_CHANNELINDEXREPLICAS`` | ++---------------------------------------------------------------+----------------------------------------------------------------------------------+ +| **Note**: If there are ``n`` data nodes, the number of replicas per shard for each index should be ``n-1``. If the number of nodes in an | +| Elasticsearch cluster changes, this configuration setting, as well as `Post Index Replicas <#post-index-shards>`__ and | +| `User Index Replicas <#user-index-replicas>`__ must also be updated accordingly. | ++---------------------------------------------------------------+----------------------------------------------------------------------------------+ + +.. config:setting:: elastic-channelindexshards + :displayname: Channel index shards (Elasticsearch) + :systemconsole: N/A + :configjson: .Elasticsearchsettings.ChannelIndexShards + :environment: MM_ELASTICSEARCHSETTINGS_CHANNELINDEXSHARDS + :description: The number of shards to use for each channel index. Default is **1**. + +Channel index shards +~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+----------------------------------------------------------------------------------+ +| The number of shards to use for each channel index. | - System Config path: N/A | +| | - ``config.json`` setting: ``".Elasticsearchsettings.ChannelIndexShards: 1",`` | +| Numerical input. Default is **1**. | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_CHANNELINDEXSHARDS`` | ++---------------------------------------------------------------+----------------------------------------------------------------------------------+ + +.. config:setting:: elastic-userindexreplicas + :displayname: User index replicas (Elasticsearch) + :systemconsole: N/A + :configjson: .Elasticsearchsettings.UserIndexReplicas + :environment: MM_ELASTICSEARCHSETTINGS_USERINDEXREPLICAS + :description: The number of replicas to use for each user index. Default is **1**. + +User index replicas +~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+-------------------------------------------------------------------------------+ +| The number of replicas to use for each user index. | - System Config path: N/A | +| | - ``config.json`` setting: ``".Elasticsearchsettings.UserIndexReplicas: 1",`` | +| Numerical input. Default is **1**. | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_USERINDEXREPLICAS`` | ++---------------------------------------------------------------+-------------------------------------------------------------------------------+ +| **Note**: If there are ``n`` data nodes, the number of replicas per shard for each index should be ``n-1``. If the number of nodes in an | +| Elasticsearch cluster changes, this configuration setting, as well as `Post Index Replicas <#post-index-replicas>`__ and | +| `Channel Index Replicas <#channel-index-replicas>`__ must also be updated accordingly. | ++---------------------------------------------------------------+-------------------------------------------------------------------------------+ + +.. config:setting:: elastic-userindexshards + :displayname: User index shards (Elasticsearch) + :systemconsole: N/A + :configjson: .Elasticsearchsettings.UserIndexShards + :environment: MM_ELASTICSEARCHSETTINGS_USERINDEXSHARDS + :description: The number of shards to use for each user index. Default is **1**. + +User index shards +~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+----------------------------------------------------------------------------------+ +| The number of shards to use for each user index. | - System Config path: N/A | +| | - ``config.json`` setting: ``".Elasticsearchsettings.UserIndexShards: 1",`` | +| Numerical input. Default is **1**. | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_USERINDEXSHARDS`` | ++---------------------------------------------------------------+----------------------------------------------------------------------------------+ + +.. config:setting:: elastic-aggregatesearchindexes + :displayname: Aggregate search indexes (Elasticsearch) + :systemconsole: N/A + :configjson: .Elasticsearchsettings.AggregatePostsAfterDays + :environment: MM_ELASTICSEARCHSETTINGS_AGGREGATEPOSTSAFTERDAYS + :description: Elasticsearch indexes older than the age specified by this setting, in days, will be aggregated during the daily scheduled job. Default is **365** days. + +Aggregate search indexes +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+----------------------------------------------------------------------------------------+ +| Elasticsearch indexes older than the age specified by this | - System Config path: N/A | +| setting, in days, will be aggregated during the daily | - ``config.json`` setting: ``".Elasticsearchsettings.AggregatePostsAfterDays: 365",`` | +| scheduled job. | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_AGGREGATEPOSTSAFTERDAYS`` | +| | | +| Numerical input. Default is **365** days. | | ++---------------------------------------------------------------+----------------------------------------------------------------------------------------+ +| **Note**: If you’re using :doc:`data retention ` and | +| :doc:`Elasticsearch `, configure this with a value greater than your data retention policy. | ++---------------------------------------------------------------+----------------------------------------------------------------------------------------+ + +.. config:setting:: elastic-postaggregatorstarttime + :displayname: Post aggregator start time (Elasticsearch) + :systemconsole: N/A + :configjson: .Elasticsearchsettings.PostsAggregatorJobStartTime + :environment: MM_ELASTICSEARCHSETTINGS_POSTSAGGREGATORJOBSTARTTIME + :description: The start time of the daily scheduled aggregator job. Must be a 24-hour time stamp in the form ``HH:MM`` based on the local time of the server. Default is **03:00** (3 AM). + +Post aggregator start time +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+---------------------------------------------------------------------------------------------+ +| The start time of the daily scheduled aggregator job. | - System Config path: N/A | +| | - ``config.json`` setting: ``".Elasticsearchsettings.PostsAggregatorJobStartTime: 03:00",`` | +| Must be a 24-hour time stamp in the form ``HH:MM`` based on | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_POSTSAGGREGATORJOBSTARTTIME`` | +| the local time of the server. | | +| | | +| Default is **03:00** (3 AM) | | ++---------------------------------------------------------------+---------------------------------------------------------------------------------------------+ + +.. config:setting:: elastic-indexprefix + :displayname: Index prefix (Elasticsearch) + :systemconsole: N/A + :configjson: .Elasticsearchsettings.IndexPrefix + :environment: MM_ELASTICSEARCHSETTINGS_INDEXPREFIX + :description: The prefix added to the Elasticsearch index name. + +Index prefix +~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| The prefix added to the Elasticsearch index name. | - System Config path: N/A | +| | - ``config.json`` setting: ``".Elasticsearchsettings.IndexPrefix",`` | +| | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_INDEXPREFIX`` | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| **Note**: When this setting is used, all Elasticsearch indexes created by Mattermost are given this prefix. You can set different | +| prefixes so that multiple Mattermost deployments can share an Elasticsearch cluster without the index names colliding. | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ + +.. config:setting:: elastic-liveindexingbatchsize + :displayname: Live indexing batch size (Elasticsearch) + :systemconsole: N/A + :configjson: .Elasticsearchsettings.LiveIndexingBatchSize + :environment: MM_ELASTICSEARCHSETTINGS_LIVEINDEXINGBATCHSIZE + :description: The number of new posts batched together before they're added to the Elasticsearch index. Default is **1**. + +Live indexing batch size +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+-----------------------------------------------------------------------------------+ +| The number of new posts needed before those posts are added | - System Config path: N/A | +| to the Elasticsearch index. Once added to the Index, | - ``config.json`` setting: ``".Elasticsearchsettings.LiveIndexingBatchSize: 1",`` | +| the post becomes searchable. | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_LIVEINDEXINGBATCHSIZE`` | +| | | +| On servers with more than 1 post per second, we suggest | | +| setting this value to the average number of posts over a | | +| 20 second period of time. | | +| | | +| Numerical input. Default is **1**. Every post is indexed | | +| synchronously as they are created. | | ++---------------------------------------------------------------+-----------------------------------------------------------------------------------+ +| **Note**: It may be necessary to increase this value to avoid hitting the rate limit or resource limit of your Elasticsearch cluster | +| on installs handling more than 1 post per second. | +| | +| **What exactly happens when I increase this value?** | +| The primary impact is that a post will be indexed into Elasticsearch after the threshold of posts is met which then makes the posts searchable | +| within Mattermost. So, if you set this based on our recommendations for larger servers, and you make a post, you cannot find it via search | +| for ~ 10-20 seconds, on average. Realistically, no users should see or feel this impact due to the limited amount of users who are actively | +| **searching** for a post this quickly. You can set this value to a lower average or higher average as well, depending on your Elasticsearch | +| server specifications. | +| | +| During busy periods, this delay will be faster as more traffic is happening, causing more posts and a quicker time to hit the index number. | +| During slow times, expect the reverse. | ++---------------------------------------------------------------+-----------------------------------------------------------------------------------+ + +**How to find the right number for your server** + +1. You must understand how many posts your server makes every minute. Run the query below to calculate your server's average posts per minute. + + Note that this query can be heavy, so we recommend that you run it during non-peak hours. + Additionally, you can adjust the ``WHERE`` clause to see the posts per minute over a different time period. Right now ``31536000000`` represents the number of milliseconds in a year. + + .. code-block:: SQL + + SELECT + AVG(postsPerMinute) as averagePostsPerMinute + FROM ( + SELECT + count(*) as postsPerMinute, + date_trunc('minute', to_timestamp(createat/1000)) + FROM posts + WHERE createAt > ( (extract(epoch from now()) * 1000 ) - 31536000000) + GROUP BY date_trunc('minute', to_timestamp(createat/1000)) + ) as ppm; + +2. Decide the acceptable index window for your environment, and divide your average posts per minute by that. We suggest 10-20 seconds. Assuming you have ``600`` posts per minute on average, and you want to index every 20 seconds (``60 seconds / 20 seconds = 3```) you would calculate ``600 / 3`` to come to the number ``200``. After 200 posts, Mattermost will index the posts into Elasticsearch. So, on average, there would be a 20-second delay in searchability. + +3. Edit the ``config.json`` or run mmctl to modify the ``LiveIndexingBatchSize`` setting + + **In the ``config.json``** + + .. code-block:: JSON + + { + "ElasticsearchSettings": { + "LiveIndexingBatchSize": 200 + } + } + + **Via mmctl** + + .. code-block:: sh + + mmctl config set ElasticsearchSettings.LiveIndexingBatchSize 200 + + **Via an environment variable** + + .. code-block:: sh + + MM_ELASTICSEARCHSETTINGS_LIVEINDEXINGBATCHSIZE = 200 + +4. Restart the Mattermost server. + +.. config:setting:: elastic-batchsize + :displayname: Batch size (Elasticsearch) + :systemconsole: N/A + :configjson: .Elasticsearchsettings.BatchSize + :environment: MM_ELASTICSEARCHSETTINGS_BATCHSIZE + :description: The number of posts for a single batch during a bulk indexing job. Default is **10000**. + +Batch size +~~~~~~~~~~~ + ++-------------------------------------------+---------------------------------------------------------------------------+ +| The number of posts for a single batch | - System Config path: N/A | +| during a bulk indexing job. | - ``config.json`` setting: ``".Elasticsearchsettings.BatchSize :10000",`` | +| | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_BATCHSIZE`` | +| Numerical input. Default is **10000**. | | ++-------------------------------------------+---------------------------------------------------------------------------+ + +.. config:setting:: elastic-requesttimeout + :displayname: Request timeout (Elasticsearch) + :systemconsole: N/A + :configjson: .Elasticsearchsettings.RequestTimeoutSeconds + :environment: MM_ELASTICSEARCHSETTINGS_REQUESTTIMEOUTSECONDS + :description: The timeout, in seconds, for Elasticsearch calls. Default is **30** seconds. + +Request timeout +~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+------------------------------------------------------------------------------------+ +| The timeout, in seconds, for Elasticsearch calls. | - System Config path: N/A | +| | - ``config.json`` setting: ``".Elasticsearchsettings.RequestTimeoutSeconds :30",`` | +| Numerical input in seconds. Default is **30** seconds. | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_REQUESTTIMEOUTSECONDS`` | ++---------------------------------------------------------------+------------------------------------------------------------------------------------+ + +.. config:setting:: elastic-trace + :displayname: Trace (Elasticsearch) + :systemconsole: N/A + :configjson: .Elasticsearchsettings.Trace + :environment: MM_ELASTICSEARCHSETTINGS_TRACE + :description: Options for printing Elasticsearch trace errors. + + - **error**: Creates the error trace when initializing the Elasticsearch client and prints any template creation or search query that returns an error as part of the error message. + - **all**: Creates the three traces (error, trace and info) for the driver and doesn’t print the queries because they will be part of the trace log level of the driver. + - **not specified**: **(Default)** No error trace is created. + +Trace +~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| Options for printing Elasticsearch trace errors. | - System Config path: N/A | +| | - ``config.json`` setting: ``".Elasticsearchsettings.Trace",`` | +| - **error**: Creates the error trace when initializing | - Environment variable: ``MM_ELASTICSEARCHSETTINGS_TRACE`` | +| the Elasticsearch client and prints any template creation | | +| or search query that returns an error as part of the | | +| error message. | | +| - **all**: Creates the three traces (error, trace and info) | | +| for the driver and doesn’t print the queries because they | | +| will be part of the trace log level of the driver. | | +| - **not specified**: **(Default)** No error trace is created. | | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ + +---- + +File storage +------------ + +.. include:: ../_static/badges/allplans-selfhosted.rst + :start-after: :nosearch: + +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. + +.. include:: ../_static/badges/academy-file-storage.rst + :start-after: :nosearch: + +.. note:: + + Mattermost currently supports storing files on the local filesystem and Amazon S3 or S3-compatible containers. We have tested Mattermost with `MinIO `__ and `Digital Ocean Spaces `__ products, but not all S3-compatible containers on the market. If you are looking to use other S3-compatible containers, we recommend completing your own testing. + +.. config:setting:: file-storagesystem + :displayname: File storage system (File Storage) + :systemconsole: Environment > File Storage + :configjson: .FileSettings.DriverName + :environment: MM_FILESETTINGS_DRIVERNAME + :description: The type of file storage system used. + + - **local**: **(Default)** Files and images are stored in the specified local file directory. + - **amazons3**: Files and images are stored on Amazon S3 based on the access key, bucket, and region fields provided. + +File storage system +~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| The type of file storage system used. | - System Config path: **Environment > File Storage** | +| Can be either Local File System or Amazon S3. | - ``config.json`` setting: ``".FileSettings.DriverName: local”,`` | +| | - Environment variable: ``MM_FILESETTINGS_DRIVERNAME`` | +| - **local**: **(Default)** Files and images are stored in | | +| the specified local file directory. | | +| - **amazons3**: Files and images are stored on Amazon S3 | | +| based on the access key, bucket, and region fields | | +| provided. The driver is compatible with MinIO (Beta) | | +| and Digital Ocean Spaces. | | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ + +.. config:setting:: file-localstoragedirectory + :displayname: Local storage directory (File Storage) + :systemconsole: Environment > File Storage + :configjson: .FileSettings.Directory + :environment: MM_FILESETTINGS_DIRECTORY + :description: The local directory to which files are written when the **File storage system** is set to **local**. Default value is **./data/**. + +Local storage directory +~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| The local directory to which files are written when the | - System Config path: **Environment > File Storage** | +| **File storage system** is set to **local**. | - ``config.json`` setting: ``".FileSettings.Directory”,`` | +| Can be any directory writable by the user Mattermost is | - Environment variable: ``MM_FILESETTINGS_DIRECTORY`` | +| running as, and is relative to the directory where | | +| Mattermost is installed. | | +| | | +| Defaults to **./data/**. | | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| **Note**: When **File storage system** is set to **amazons3**, this setting has no effect. | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ + +.. config:setting:: file-maxfilesize + :displayname: Maximum file size (File Storage) + :systemconsole: Environment > File Storage + :configjson: .FileSettings.MaxFileSize + :environment: MM_FILESETTINGS_MAXFILESIZE + :description: The maximum file size, in bytes, for message attachments and plugin uploads. Default value is **104857600** bytes (100 mebibytes). + +Maximum file size +~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++-------------------------------------------------------------------+--------------------------------------------------------------------------+ +| The maximum file size for message attachments and plugin | - System Config path: **Environment > File Storage** | +| uploads. This value must be specified in mebibytes in the | - ``config.json`` setting: ``".FileSettings.MaxFileSize: 104857600",`` | +| System Console, and in bytes in the ``config.json`` file. | - Environment variable: ``MM_FILESETTINGS_MAXFILESIZE`` | +| | | +| The default is ``104857600`` bytes (**100** mebibytes). | | ++-------------------------------------------------------------------+--------------------------------------------------------------------------+ +| **Warning**: Verify server memory can support your setting choice. Large file sizes increase the risk of server crashes and failed | +| uploads due to network disruptions. | ++-------------------------------------------------------------------+--------------------------------------------------------------------------+ +| **Notes**: | +| | +| - When :ref:`uploading plugin files `, a ``Received invlaid response from | +| the server`` error typically indicates that ``MaxFileSize`` isn't large enough to support the plugin file upload, and/or that proxy | +| settings may not be sufficient. | +| - If you use a proxy or load balancer in front of Mattermost, the following proxy settings must be adjusted accordingly: | +| | +| - For NGINX, use ``client_max_body_size``. | +| - For Apache use ``LimitRequestBody``. | ++-------------------------------------------------------------------+--------------------------------------------------------------------------+ + +.. config:setting:: file-enabledocsearchbycontent + :displayname: Enable document search by content (File Storage) + :systemconsole: Environment > File Storage + :configjson: .FileSettings.ExtractContent + :environment: MM_FILESETTINGS_EXTRACTCONTENT + :description: Enable users to search the contents of documents attached to messages. + + - **true**: **(Default)** Documents are searchable by their content. + - **false**: Documents aren’t searchable by their content. + +Enable document search by content +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+-------------------------------------------------------------------------------------+ +| Enable users to search the contents of documents attached | - System Config path: **Environment > File Storage** | +| to messages. | - ``config.json`` setting: ``".FileSettings.ExtractContent: true",`` | +| | - Environment variable: ``MM_FILESETTINGS_EXTRACTCONTENT`` | +| - **true**: **(Default)** Documents are searchable by | | +| their content. | | +| - **false**: Documents aren’t searchable by their content. | | +| When document content search is disabled, users can search | | +| for files by file name only. | | ++---------------------------------------------------------------+-------------------------------------------------------------------------------------+ +| **Note**: Document content search results for files shared before upgrading to Mattermost Server v5.35 may be incomplete until an | +| extraction command is executed using the :ref:`mmctl `. | +| If this command is not run, users can search older files based on file name only. | +| | +| You can optionally install the following `dependencies `__ to extend content searching support in | +| Mattermost to include file formats beyond PDF, DOCX, and ODT, such as DOC, RTF, XML, and HTML: | +| | +| - **tidy**: Used to search the contents of HTML documents. | +| - **wv**: Used to search the contents of DOC documents. | +| - **popplerutils**: Used to significantly improve server performance when extracting the contents of PDF documents. | +| - **unrtf**: Used to search the contents of RTF documents. | +| - **JusText**: Used to search HTML documents. | +| | +| If you choose not to install these dependencies, you’ll see log entries for documents that couldn’t be extracted. | +| Any documents that can’t be extracted are skipped and logged so that content extraction can proceed. | ++---------------------------------------------------------------+-------------------------------------------------------------------------------------+ + +.. config:setting:: file-enabledocsearchwithinzipfile + :displayname: Enable searching content of documents within ZIP files (File Storage) + :systemconsole: Environment > File Storage + :configjson: .FileSettings.ArchiveRecursion + :environment: MM_FILESETTINGS_ARCHIVERECURSION + :description: Enables users to search the contents of compressed ZIP files attached to messages. + + - **true**: Contents of documents within ZIP files are returned in search results. + - **false**: **(Default)** The contents of documents within ZIP files aren’t returned in search results. + +Enable searching content of documents within ZIP files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+----------------------------------------------------------------------------------------+ +| Enables users to search the contents of compressed ZIP files | - System Config path: **Environment > File Storage** | +| attached to messages. | - ``config.json`` setting: ``".FileSettings.ArchiveRecursion: false",`` | +| | - Environment variable: ``MM_FILESETTINGS_ARCHIVERECURSION`` | +| - **true**: Contents of documents within ZIP files are | | +| returned in search results. This may have an impact on | | +| server performance for large files. | | +| the specified local file directory. | | +| - **false**: **(Default)** The contents of documents within | | +| ZIP files aren’t returned in search results. | | ++---------------------------------------------------------------+----------------------------------------------------------------------------------------+ +| **Note**: Document content search within ZIP files is available, with mobile support coming soon. | +| Searching document contents adds load to your server. For large deployments, or teams that share many large, text-heavy documents, | +| we recommend you review our :ref:`hardware requirements `, | +| and test enabling this feature in a staging environment before enabling it in a production environment. | ++---------------------------------------------------------------+----------------------------------------------------------------------------------------+ + +.. config:setting:: file-s3bucket + :displayname: Amazon S3 bucket (File Storage) + :systemconsole: Environment > File Storage + :configjson: .FileSettings.AmazonS3Bucket + :environment: MM_FILESETTINGS_AMAZONS3BUCKET + :description: The name of the bucket for your S3-compatible object storage instance. + +Amazon S3 bucket +~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| The name of the bucket for your S3-compatible object | - System Config path: **Environment > File Storage** | +| storage instance. | - ``config.json`` setting: ``".FileSettings.AmazonS3Bucket",`` | +| | - Environment variable: ``MM_FILESETTINGS_AMAZONS3BUCKET`` | +| A string with the S3-compatible bucket name. | | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ + +.. config:setting:: file-s3pathprefix + :displayname: Amazon S3 path prefix (File Storage) + :systemconsole: N/A + :configjson: .FileSettings.AmazonS3PathPrefix + :environment: MM_FILESETTINGS_AMAZONS3PATHPREFIX + :description: The prefix you selected for your **Amazon S3 bucket** in AWS. + +Amazon S3 path prefix +~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| The prefix you selected for your **Amazon S3 bucket** in AWS. | - System Config path: N/A | +| | - ``config.json`` setting: ``".FileSettings.AmazonS3PathPrefix",`` | +| A string containing the path prefix. | - Environment variable: ``MM_FILESETTINGS_AMAZONS3PATHPREFIX`` | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ + +.. config:setting:: file-s3region + :displayname: Amazon S3 region (File Storage) + :systemconsole: Environment > File Storage + :configjson: .FileSettings.AmazonS3Region + :environment: MM_FILESETTINGS_AMAZONS3REGION + :description: The AWS region you selected when creating your **Amazon S3 bucket** in AWS. For MinIO or Digital Ocean Spaces, leave this setting empty. + +Amazon S3 region +~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| The AWS region you selected when creating your | - System Config path: **Environment > File Storage** | +| **Amazon S3 bucket** in AWS. | - ``config.json`` setting: ```".FileSettings.AmazonS3Region",`` | +| | - Environment variable: ``MM_FILESETTINGS_AMAZONS3REGION`` | +| A string with the AWS region containing the bucket. | | +| If no region is set, Mattermost attempts to get the | | +| appropriate region from AWS, and sets it to **us-east-1** | | +| if none found. | | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| **Note**: For MinIO or Digital Ocean Spaces, leave this setting empty. | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ + +.. config:setting:: file-s3accesskeyid + :displayname: Amazon S3 access key ID (File Storage) + :systemconsole: Environment > File Storage + :configjson: .FileSettings.AmazonS3AccessKeyId + :environment: MM_FILESETTINGS_AMAZONS3ACCESSKEYID + :description: A string with the access key for the S3-compatible storage instance. + +Amazon S3 access key ID +~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| A string with the access key for the S3-compatible storage | - System Config path: **Environment > File Storage** | +| instance. Your EC2 administrator can supply you with the | - ``config.json`` setting: ``".FileSettings.AmazonS3AccessKeyId",`` | +| Access Key ID. | - Environment variable: ``MM_FILESETTINGS_AMAZONS3ACCESSKEYID`` | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| **Note**: This is required for access unless you are using an | +| `Amazon S3 IAM Role `__ with | +| Amazon S3. | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ + +.. config:setting:: file-s3endpoint + :displayname: Amazon S3 endpoint (File Storage) + :systemconsole: Environment > File Storage + :configjson: .FileSettings.AmazonS3Endpoint + :environment: MM_FILESETTINGS_AMAZONS3ENDPOINT + :description: The hostname of your S3-compatible instance. Default value is **s3.amazonaws.com**. + +Amazon S3 endpoint +~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+------------------------------------------------------------------------------------+ +| The hostname of your S3-compatible instance. | - System Config path: **Environment > File Storage** | +| | - ``config.json`` setting: ``".FileSettings.AmazonS3Endpoint: s3.amazonaws.com",`` | +| A string with the hostname of the S3-compatible storage | - Environment variable: ``MM_FILESETTINGS_AMAZONS3ENDPOINT`` | +| instance. Defaults to **s3.amazonaws.com**. | | ++---------------------------------------------------------------+------------------------------------------------------------------------------------+ +| **Note**: For Digital Ocean Spaces, the hostname should be set to **.digitaloceanspaces.com**, where **** is the abbreviation | +| for the region you selected when setting up the Space. It can be **nyc3**, **ams3**, or **sgp1**. | ++---------------------------------------------------------------+------------------------------------------------------------------------------------+ + +.. config:setting:: file-s3secretaccesskey + :displayname: Amazon S3 secret access key (File Storage) + :systemconsole: Environment > File Storage + :configjson: .FileSettings.AmazonS3SecretAccessKey + :environment: MM_FILESETTINGS_AMAZONS3SECRETACCESSKEY + :description: The secret access key associated with your Amazon S3 Access Key ID. + +Amazon S3 secret access key +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| The secret access key associated with your Amazon S3 | - System Config path: **Environment > File Storage** | +| Access Key ID. | - ``config.json`` setting: ``".FileSettings.AmazonS3SecretAccessKey",`` | +| | - Environment variable: ``MM_FILESETTINGS_AMAZONS3SECRETACCESSKEY`` | +| A string with the secret access key for the S3-compatible | | +| storage instance. | | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ + +.. config:setting:: file-s3secureconnection + :displayname: Enable secure Amazon S3 connections (File Storage) + :systemconsole: Environment > File Storage + :configjson: .FileSettings.AmazonS3SSL + :environment: MM_FILESETTINGS_AMAZONS3SSL + :description: Enable or disable secure Amazon S3 connections. Default value is **true**. + +Enable secure Amazon S3 connections +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| Enable or disable secure Amazon S3 connections. | - System Config path: **Environment > File Storage** | +| | - ``config.json`` setting: ``".FileSettings.AmazonS3SSL: true",`` | +| - **true**: **(Default)** Enables only secure Amazon | - Environment variable: ``MM_FILESETTINGS_AMAZONS3SSL`` | +| S3 connections. | | +| - **false**: Allows insecure connections to Amazon S3. | | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ + +.. config:setting:: file-s3signv2 + :displayname: Amazon S3 signature v2 (File Storage) + :systemconsole: N/A + :configjson: .FileSettings.AmazonS3SignV2 + :environment: MM_FILESETTINGS_AMAZONS3SIGNV2 + + - **true**: Use Signature v2 signing process. + - **false**: **(Default)** Use Signature v4 signing process. + +Amazon S3 signature v2 +~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Not available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| By default, Mattermost uses Signature v4 to sign API calls | - System Config path: N/A | +| to AWS, but under some circumstances, v2 is required. | - ``config.json`` setting: ``".FileSettings.AmazonS3SignV2: false",`` | +| | - Environment variable: ``MM_FILESETTINGS_AMAZONS3SIGNV2`` | +| - **true**: Use Signature v2 signing process. | | +| - **false**: **(Default)** Use Signature v4 signing process. | | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| See the `AWS `__ documentation for information about when to | +| use the Signature v2 signing process. | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ + +.. config:setting:: file-s3sse + :displayname: Enable server-side encryption for Amazon S3 (File Storage) + :systemconsole: Environment > File Storage + :configjson: .FileSettings.AmazonS3SSE + :environment: MM_FILESETTINGS_AMAZONS3SSE + + - **true**: Encrypts files in Amazon S3 using server-side encryption with Amazon S3-managed keys. + - **false**: **(Default)** Doesn’t encrypt files in Amazon S3. + +Enable server-side encryption for Amazon S3 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E20

+ ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| Enable server-side encryption for Amazon S3. | - System Config path: **Environment > File Storage** | +| | - ``config.json`` setting: ``".FileSettings.AmazonS3SSE: false",`` | +| - **true**: Encrypts files in Amazon S3 using server-side | - Environment variable: ``MM_FILESETTINGS_AMAZONS3SSE`` | +| encryption with Amazon S3-managed keys. | | +| - **false**: **(Default)** Doesn’t encrypt files in | | +| Amazon S3. | | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ + +.. config:setting:: file-s3trace + :displayname: Enable Amazon S3 debugging (File Storage) + :systemconsole: Environment > File Storage + :configjson: .FileSettings.AmazonS3Trace + :environment: MM_FILESETTINGS_AMAZONS3TRACE + + - **true**: Log additional debugging information is logged to the system logs. + - **false**: **(Default)** No Amazon S3 debugging information is included in the system logs. + +Enable Amazon S3 debugging +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| Enable or disable Amazon S3 debugging to capture additional | - System Config path: **Environment > File Storage** | +| debugging information in system logs | - ``config.json`` setting: ``".FileSettings.AmazonS3Trace: false",`` | +| | - Environment variable: ``MM_FILESETTINGS_AMAZONS3TRACE`` | +| - **true**: Log additional debugging information is logged | | +| to the system logs. | | +| - **false**: **(Default)** No Amazon S3 debugging information | | +| is included in the system logs. Typically set to **false** | | +| in production. | | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ +| Select the **Test Connection** button in the System Console to validate the settings and ensure the user can access the server. | ++---------------------------------------------------------------+--------------------------------------------------------------------------+ + +.. config:setting:: file-amazons3requesttimeoutmilliseconds + :displayname: Amazon S3 request timeout (File Storage) + :systemconsole: N/A + :configjson: .FileSettings.AmazonS3RequestTimeoutMilliseconds + :environment: MM_FILESETTINGS_AMAZONS3REQUESTTIMEOUTMILLISECONDS + :description: Amount of time, in milliseconds, before requests to Amazon S3 time out. Default value is 30000 (30 seconds). + +Amazon S3 request timeout +~~~~~~~~~~~~~~~~~~~~~~~~~ + ++---------------------------------------------------------------+-----------------------------------------------------------------------------------------+ +| The amount of time, in milliseconds, before requests to | - System Config path: N/A | +| Amazon S3 storage time out. | - ``config.json`` setting: ``".FileSettings.AmazonS3RequestTimeoutMilliseconds: 30000`` | +| | - Environment variable: ``MM_FILESETTINGS_AMAZONS3REQUESTTIMEOUTMILLISECONDS`` | +| Default is 30000 (30 seconds). | | ++---------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + +.. config:setting:: file-amazons3uploadpartsizebytes + :displayname: Amazon S3 upload part size (File Storage) + :systemconsole: N/A + :configjson: .FileSettings.AmazonS3UploadPartSizeBytes + :environment: MM_FILESETTINGS_AMAZONS3UPLOADPARTSIZEBYTES + :description: The size, in bytes, of each part in a multi-part upload to Amazon S3. Default value is 5242880 (5MB). + +Amazon S3 upload part size +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++---------------------------------------------------------------+---------------------------------------------------------------------------------------+ +| The size, in bytes, of each part in a multi-part | - System Config path: N/A | +| upload to Amazon S3. | - ``config.json`` setting: ``".FileSettings.AmazonS3UploadPartSizeBytes: 5242880`` | +| | - Environment variable: ``MM_FILESETTINGS_AMAZONS3UPLOADPARTSIZEBYTES`` | +| Numeric value. Default is 5242880 (5MB). | | ++---------------------------------------------------------------+---------------------------------------------------------------------------------------+ +| **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. | ++---------------------------------------------------------------+---------------------------------------------------------------------------------------+ + +.. config:setting:: file-exportamazons3uploadpartsizebytes + :displayname: Export Amazon S3 upload part size (File Storage) + :systemconsole: N/A + :configjson: .FileSettings.ExportAmazonS3UploadPartSizeBytes + :environment: MM_FILESETTINGS_EXPORTAMAZONS3UPLOADPARTSIZEBYTES + :description: The size, in bytes, of each part in a multi-part exported to Amazon S3. Default value is 104857600 (100MB). + +Amazon S3 exported upload part size +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++---------------------------------------------------------------+--------------------------------------------------------------------------------------------+ +| The size, in bytes, of each part in a multi-part | - System Config path: N/A | +| exported to Amazon S3. | - ``config.json`` setting: ``".FileSettings.ExportAmazonS3UploadPartSizeBytes: 104857600`` | +| | - Environment variable: ``MM_FILESETTINGS_EXPORTAMAZONS3UPLOADPARTSIZEBYTES`` | +| Numeric value. Default is 104857600 (100MB). | | ++---------------------------------------------------------------+--------------------------------------------------------------------------------------------+ +| **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. | ++---------------------------------------------------------------+--------------------------------------------------------------------------------------------+ + +.. config:setting:: file-initialfont + :displayname: Initial font (File Storage) + :systemconsole: N/A + :configjson: .FileSettings.InitialFont + :environment: MM_FILESETTINGS_INITIALFONT + :description: The font used in auto-generated profile pictures with colored backgrounds and username initials. Default value is **nunito-bold.ttf**. + +Initial font +~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+--------------------------------------------------------------------------------+ +| The font used in auto-generated profile pictures with colored | - System Config path: N/A | +| backgrounds and username initials. | - ``config.json`` setting: ``".FileSettings.InitialFont: nunito-bold.ttf",`` | +| | - Environment variable: ``MM_FILESETTINGS_INITIALFONT`` | +| A string with the font file name. Default is | | +| **nunito-bold.ttf**. | | ++---------------------------------------------------------------+--------------------------------------------------------------------------------+ + +.. config:setting:: file-amazons3requesttimeoutmilliseconds + :displayname: Amazon S3 request timeout (File Storage) + :systemconsole: N/A + :configjson: .FileSettings.AmazonS3RequestTimeoutMilliseconds + :environment: MM_FILESETTINGS_AMAZONS3REQUESTTIMEOUTMILLISECONDS + :description: Amount of time, in milliseconds, before requests to Amazon S3 time out. Default value is 30000 (30 seconds). + +Amazon S3 request timeout +~~~~~~~~~~~~~~~~~~~~~~~~~ + ++---------------------------------------------------------------+-----------------------------------------------------------------------------------------+ +| The amount of time, in milliseconds, before requests to | - System Config path: N/A | +| Amazon S3 storage time out. | - ``config.json`` setting: ``".FileSettings.AmazonS3RequestTimeoutMilliseconds: 30000`` | +| | - Environment variable: ``MM_FILESETTINGS_AMAZONS3REQUESTTIMEOUTMILLISECONDS`` | +| Default is 30000 (30 seconds). | | ++---------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + +---- + +Image proxy +----------- + +.. include:: ../_static/badges/allplans-selfhosted.rst + :start-after: :nosearch: + +An image proxy is used by Mattermost apps to prevent them from connecting directly to remote self-hosted servers. Configure an image proxy by going to **System Console > Environment > Image Proxy**, or by editing the ``config.json`` file as described in the following tables. + +.. config:setting:: image-enableproxy + :displayname: Enable image proxy (Image Proxy) + :systemconsole: Environment > Image Proxy + :configjson: .ImageProxySettings.Enable + :environment: MM_IMAGEPROXYSETTINGS_ENABLE + + - **true**: **(Default)** Enables an image proxy for loading external images. + - **false**: Disables the image proxy. + +Enable image proxy +~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+---------------------------------------------------------------------+ +| An image proxy anonymizes Mattermost app connections and | - System Config path: **Environment > Image Proxy** | +| prevents them from accessing insecure content. | - ``config.json setting``: ``".ImageProxySettings.Enable": true",`` | +| | - Environment variable: ``MM_IMAGEPROXYSETTINGS_ENABLE`` | +| - **true**: **(Default)** Enables an image proxy for loading | | +| external images. | | +| - **false**: Disables the image proxy. | | ++---------------------------------------------------------------+---------------------------------------------------------------------+ +| See the :doc:`image proxy ` documentation to learn more. | ++---------------------------------------------------------------+---------------------------------------------------------------------+ + +.. config:setting:: image-proxytype + :displayname: Image proxy type (Image Proxy) + :systemconsole: Environment > Image Proxy + :configjson: .ImageProxySettings.ImageProxyType + :environment: MM_IMAGEPROXYSETTINGS_IMAGEPROXYTYPE + :description: The type of image proxy used by Mattermost. + + - **local**: **(Default)** The Mattermost server itself acts as the image proxy. + - **atmos/camo**: An external atmos/camo image proxy is used. + +Image proxy type +~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+-------------------------------------------------------------------------------+ +| The type of image proxy used by Mattermost. | - System Config path: **Environment > Image Proxy** | +| | - ``config.json setting``: ``".ImageProxySettings.ImageProxyType": "local",`` | +| - **local**: **(Default)** The Mattermost server itself acts | - Environment variable: ``MM_IMAGEPROXYSETTINGS_IMAGEPROXYTYPE`` | +| as the image proxy. | | +| - **atmos/camo**: An external atmos/camo image proxy is used. | | ++---------------------------------------------------------------+-------------------------------------------------------------------------------+ +| See the :doc:`image proxy ` documentation to learn more. | ++---------------------------------------------------------------+-------------------------------------------------------------------------------+ + +.. config:setting:: image-remoteimageproxyurl + :displayname: Remote image proxy URL (Image Proxy) + :systemconsole: Environment > Image Proxy + :configjson: .ImageProxySettings.RemoteImageProxyURL + :environment: MM_IMAGEPROXYSETTINGS_REMOTEIMAGEPROXYURL + :description: The URL of the atmos/camo proxy. + +Remote image proxy URL +~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+---------------------------------------------------------------------------+ +| The URL of the atmos/camo proxy. This setting isn't needed | - System Config path: **Environment > Image Proxy** | +| when using the **local** image proxy. | - ``config.json setting``: ``".ImageProxySettings.RemoteImageProxyURL",`` | +| | - Environment variable: ``MM_IMAGEPROXYSETTINGS_REMOTEIMAGEPROXYURL`` | ++---------------------------------------------------------------+---------------------------------------------------------------------------+ + +.. config:setting:: image-remoteimageproxyoptions + :displayname: Remote image proxy options (Image Proxy) + :systemconsole: Environment > Image Proxy + :configjson: .ImageProxySettings.RemoteImageProxyOptions + :environment: MM_IMAGEPROXYSETTINGS_REMOTEIMAGEPROXYOPTIONS + :description: The URL signing key passed to an atmos/camo image proxy. + +Remote image proxy options +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------------------+-------------------------------------------------------------------------------+ +| The URL signing key passed to an atmos/camo image proxy. | - System Config path: **Environment > Image Proxy** | +| This setting isn't needed when using the **local** image | - ``config.json setting``: ``".ImageProxySettings.RemoteImageProxyOptions",`` | +| proxy type. | - Environment variable: ``MM_IMAGEPROXYSETTINGS_REMOTEIMAGEPROXYOPTIONS`` | ++---------------------------------------------------------------+-------------------------------------------------------------------------------+ +| See the :doc:`image proxy ` documentation to learn more. | ++---------------------------------------------------------------+-------------------------------------------------------------------------------+ + +---- + +SMTP +---- + +.. include:: ../_static/badges/allplans-selfhosted.rst + :start-after: :nosearch: + +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. + +.. config:setting:: smtp-server + :displayname: SMTP server (SMTP) + :systemconsole: Environment > SMTP + :configjson: .EmailSettings.SMTPServer + :environment: MM_EMAILSETTINGS_SMTPSERVER + :description: The location of the SMTP email server used for email notifications. + +SMTP server +~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++-----------------------------------------------------------------+---------------------------------------------------------------+ +| The location of the SMTP email server used for email | - System Config path: **Environment > SMTP** | +| notifications. | - ``config.json setting``: ``".EmailSettings.SMTPServer",`` | +| | - Environment variable: ``MM_EMAILSETTINGS_SMTPSERVER`` | ++-----------------------------------------------------------------+---------------------------------------------------------------+ + +.. config:setting:: smtp-port + :displayname: SMTP server port (SMTP) + :systemconsole: Environment > SMTP + :configjson: .EmailSettings.SMTPPort + :environment: MM_EMAILSETTINGS_SMTPPORT + :description: The port of SMTP email server. + +SMTP server port +~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++-----------------------------------------------------------------+---------------------------------------------------------------+ +| The port of SMTP email server. | - System Config path: **Environment > SMTP** | +| | - ``config.json setting``: ``".EmailSettings.SMTPPort",`` | +| Numerical input. | - Environment variable: ``MM_EMAILSETTINGS_SMTPPORT`` | ++-----------------------------------------------------------------+---------------------------------------------------------------+ + +.. config:setting:: smtp-enableauth + :displayname: Enable SMTP authentication (SMTP) + :systemconsole: Environment > SMTP + :configjson: .EmailSettings.EnableSMTPAuth + :environment: MM_EMAILSETTINGS_ENABLESMTPAUTH + + - **true**: SMTP username and password are used for authenticating to the SMTP server. + - **false**: **(Default)** Mattermost doesn’t attempt to authenticate to the SMTP server. + +Enable SMTP authentication +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++-----------------------------------------------------------------+---------------------------------------------------------------------------+ +| Enable or disable SMTP authentication. | - System Config path: **Environment > SMTP** | +| | - ``config.json setting``: ``".EmailSettings.EnableSMTPAuth": false",`` | +| - **true**: SMTP username and password are used for | - Environment variable: ``MM_EMAILSETTINGS_ENABLESMTPAUTH`` | +| authenticating to the SMTP server. | | +| - **false**: **(Default)** Mattermost doesn’t attempt to | | +| authenticate to the SMTP server. | | ++-----------------------------------------------------------------+---------------------------------------------------------------------------+ + +.. config:setting:: smtp-username + :displayname: SMTP server username (SMTP) + :systemconsole: Environment > SMTP + :configjson: .EmailSettings.SMTPUsername + :environment: MM_EMAILSETTINGS_SMTPUSERNAME + :description: The username for authenticating to the SMTP server. + +SMTP server username +~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++-----------------------------------------------------------------+---------------------------------------------------------------+ +| The username for authenticating to the SMTP server. | - System Config path: **Environment > SMTP** | +| | - ``config.json setting``: ``".EmailSettings.SMTPUsername",`` | +| String input. | - Environment variable: ``MM_EMAILSETTINGS_SMTPUSERNAME`` | ++-----------------------------------------------------------------+---------------------------------------------------------------+ + +.. config:setting:: smtp-password + :displayname: SMTP server password (SMTP) + :systemconsole: Environment > SMTP + :configjson: .EmailSettings.SMTPPassword + :environment: MM_EMAILSETTINGS_SMTPPASSWORD + :description: The password associated with the SMTP username. + +SMTP server password +~~~~~~~~~~~~~~~~~~~~ -Both self-hosted and Cloud admins can access the following configuration settings in **System Console > Environment**. Self-hosted admins can also edit the ``config.json`` file as described in the following tables. +.. raw:: html -Web server ----------- +

Also available in legacy Mattermost Enterprise Edition E10 or E20

-.. include:: ../_static/badges/allplans-selfhosted.rst - :start-after: :nosearch: ++-----------------------------------------------------------------+---------------------------------------------------------------+ +| The password associated with the SMTP username. | - System Config path: **Environment > SMTP** | +| | - ``config.json setting``: ``".EmailSettings.SMTPPassword",`` | +| String input. | - Environment variable: ``MM_EMAILSETTINGS_SMTPPASSWORD`` | ++-----------------------------------------------------------------+---------------------------------------------------------------+ -.. include:: web-server-configuration-settings.rst - :start-after: :nosearch: +.. config:setting:: smtp-connectionsecurity + :displayname: SMTP connection security (SMTP) + :systemconsole: Environment > SMTP + :configjson: .EmailSettings.ConnectionSecurity + :environment: MM_EMAILSETTINGS_CONNECTIONSECURITY ----- + - **Not specified**: **(Default)** Send email over an unsecure connection. + - **TLS**: Communication between Mattermost and your email server is encrypted. + - **STARTTLS**: Attempts to upgrade an existing insecure connection to a secure connection using TLS. -Database --------- +SMTP connection security +~~~~~~~~~~~~~~~~~~~~~~~~ -.. include:: ../_static/badges/allplans-selfhosted.rst - :start-after: :nosearch: +.. raw:: html -.. include:: database-configuration-settings.rst - :start-after: :nosearch: +

Also available in legacy Mattermost Enterprise Edition E10 or E20

----- ++-----------------------------------------------------------------+-----------------------------------------------------------------------+ +| Specify connection security for emails sent using SMTP. | - System Config path: **Environment > SMTP** | +| | - ``config.json setting``: ``".EmailSettings.ConnectionSecurity",`` | +| - **Not specified**: **(Default)** Send email over an | - Environment variable: ``MM_EMAILSETTINGS_CONNECTIONSECURITY`` | +| unsecure connection. | | +| - **TLS**: Communication between Mattermost and your email | | +| server is encrypted. | | +| - **STARTTLS**: Attempts to upgrade an existing insecure | | +| connection to a secure connection using TLS. | | ++-----------------------------------------------------------------+-----------------------------------------------------------------------+ -Elasticsearch -------------- +.. config:setting:: smtp-skipservercertverification + :displayname: Skip server certificate verification (SMTP) + :systemconsole: Environment > SMTP + :configjson: .EmailSettings.SkipServerCertificateVerification + :environment: MM_EMAILSETTINGS_SKIPSERVERCERTIFICATEVERIFICATION -.. include:: ../_static/badges/ent-selfhosted.rst - :start-after: :nosearch: + - **true**: Mattermost won't verify the email server certificate. + - **false**: **(Default)** Mattermost verifies the email server certificate. -.. include:: elasticsearch-configuration-settings.rst - :start-after: :nosearch: +Skip server certificate verification +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ----- +.. raw:: html -File storage ------------- +

Also available in legacy Mattermost Enterprise Edition E10 or E20

-.. include:: ../_static/badges/allplans-selfhosted.rst - :start-after: :nosearch: ++-----------------------------------------------------------------------+----------------------------------------------------------------------------------------------+ +| Configure Mattermost to skip the verification of the email server | - System Config path: **Environment > SMTP** | +| certificate. | - ``config.json setting``: ``".EmailSettings.SkipServerCertificateVerification": false",`` | +| | - Environment variable: ``MM_EMAILSETTINGS_SKIPSERVERCERTIFICATEVERIFICATION`` | +| - **true**: Mattermost won't verify the email server certificate. | | +| - **false**: **(Default)** Mattermost verifies the email | | +| server certificate. | | ++-----------------------------------------------------------------------+----------------------------------------------------------------------------------------------+ -.. include:: file-storage-configuration-settings.rst - :start-after: :nosearch: +.. config:setting:: smtp-enablesecurityalerts + :displayname: Enable security alerts (SMTP) + :systemconsole: Environment > SMTP + :configjson: .ServiceSettings.EnableSecurityFixAlert + :environment: MM_SERVICESETTINGS_ENABLESECURITYFIXALERT ----- + - **true**: **(Default)** System admins are notified by email if a relevant security fix alert is announced. Requires email to be enabled. + - **false**: Security alerts are disabled. -Image proxy ------------ +Enable security alerts +~~~~~~~~~~~~~~~~~~~~~~ -.. include:: ../_static/badges/allplans-selfhosted.rst - :start-after: :nosearch: +.. raw:: html -.. include:: image-proxy-configuration-settings.rst - :start-after: :nosearch: +

Also available in legacy Mattermost Enterprise Edition E10 or E20

----- ++-----------------------------------------------------------------+------------------------------------------------------------------------------------+ +| Enable or disable security alerts. | - System Config path: **Environment > SMTP** | +| | - ``config.json setting``: ``".ServiceSettings.EnableSecurityFixAlert": true",`` | +| - **true**: **(Default)** System admins are notified by email | - Environment variable: ``MM_SERVICESETTINGS_ENABLESECURITYFIXALERT`` | +| if a relevant security fix alert is announced. Requires email | | +| to be enabled. | | +| - **false**: Security alerts are disabled. | | ++-----------------------------------------------------------------+------------------------------------------------------------------------------------+ +| See the :ref:`Telemetry ` documentation to learn more. | ++-----------------------------------------------------------------+------------------------------------------------------------------------------------+ -SMTP ----- +.. config:setting:: smtp-servertimeout + :displayname: SMTP server timeout (SMTP) + :systemconsole: Environment > SMTP + :configjson: .EmailSettings.SMTPServerTimeout + :environment: MM_EMAILSETTINGS_SMTPSERVERTIMEOUT + :description: The maximum amount of time, in seconds, allowed for establishing a TCP connection between Mattermost and the SMTP server. -.. include:: ../_static/badges/allplans-selfhosted.rst - :start-after: :nosearch: +SMTP server timeout +~~~~~~~~~~~~~~~~~~~ -.. include:: smtp-configuration-settings.rst - :start-after: :nosearch: +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++-----------------------------------------------------------------+----------------------------------------------------------------------+ +| The maximum amount of time, in seconds, allowed for | - System Config path: **Environment > SMTP** | +| establishing a TCP connection between Mattermost and the SMTP | - ``config.json setting``: ``".EmailSettings.SMTPServerTimeout",`` | +| server. | - Environment variable: ``MM_EMAILSETTINGS_SMTPSERVERTIMEOUT`` | +| | | +| Numerical value in seconds. | | ++-----------------------------------------------------------------+----------------------------------------------------------------------+ ---- @@ -92,8 +2996,283 @@ High availability .. include:: ../_static/badges/ent-selfhosted.rst :start-after: :nosearch: -.. include:: high-availability-configuration-settings.rst - :start-after: :nosearch: +You can configure Mattermost as a :doc:`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. + +.. config:setting:: ha-enable + :displayname: Enable high availability mode (High Availability) + :systemconsole: Environment > High Availability + :configjson: .ClusterSettings.Enable + :environment: MM_CLUSTERSETTINGS_ENABLE + + - **true**: The Mattermost server will attempt inter-node communication with the other servers in the cluster that have the same cluster name. + - **false**: **(Default)** Mattermost high availability mode is disabled. + +Enable high availability mode +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E20

+ ++-----------------------------------------------------------------+------------------------------------------------------------+ +| You can enable high availability mode. | - System Config path: **Environment > High Availability** | +| | - ``config.json`` setting: ``".ClusterSettings.Enable",`` | +| - **true**: The Mattermost server will attempt inter-node | - Environment variable: ``MM_CLUSTERSETTINGS_ENABLE`` | +| communication with the other servers in the cluster that | | +| have the same cluster name. This sets the System Console to | | +| read-only mode to keep the servers' ``config.json`` files | | +| in sync. | | +| - **false**: **(Default)** Mattermost high availability mode | | +| is disabled. | | ++-----------------------------------------------------------------+------------------------------------------------------------+ + +.. config:setting:: ha-clustername + :displayname: Cluster name (High Availability) + :systemconsole: Environment > High Availability + :configjson: .ClusterSettings.ClusterName + :environment: MM_CLUSTERSETTINGS_CLUSTERNAME + :description: The cluster to join by name in a high availability cluster-based deployment. + +Cluster name +~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E20

+ ++------------------------------------------------------------------------------+-----------------------------------------------------------------+ +| The cluster to join by name in a high availability cluster-based deployment. | - System Config path: **Environment > High Availability** | +| | - ``config.json`` setting: ``".ClusterSettings.ClusterName",`` | +| Only nodes with the same cluster name will join together. | - Environment variable: ``MM_CLUSTERSETTINGS_CLUSTERNAME`` | +| This is to support blue-green deployments or staging pointing | | +| to the same database. | | ++------------------------------------------------------------------------------+-----------------------------------------------------------------+ + +.. config:setting:: ha-overridehostname + :displayname: Override hostname (High Availability) + :systemconsole: Environment > High Availability + :configjson: .ClusterSettings.OverrideHostname + :environment: MM_CLUSTERSETTINGS_OVERRIDEHOSTNAME + :description: Override the hostname of this server. + +Override hostname +~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E20

+ ++-----------------------------------------------------------------+------------------------------------------------------------------------+ +| You can override the hostname of this server. | - System Config path: **Environment > High Availability** | +| | - ``config.json`` setting: ``".ClusterSettings.OverrideHostname",`` | +| - This property can be set to a specific IP address if needed; | - Environment variable: ``MM_CLUSTERSETTINGS_OVERRIDEHOSTNAME`` | +| however, we don’t recommend overriding the hostname unless | | +| it's necessary. | | +| - If left blank, Mattermost attempts to get the hostname from | | +| the operating system or uses the IP address. | | ++-----------------------------------------------------------------+------------------------------------------------------------------------+ +| See the :doc:`high availability cluster-based deployment ` documentation for details. | ++-----------------------------------------------------------------+------------------------------------------------------------------------+ + +.. config:setting:: ha-useipaddress + :displayname: Use IP address (High Availability) + :systemconsole: Environment > High Availability + :configjson: .ClusterSettings.UseIPAddress + :environment: MM_CLUSTERSETTINGS_USEIPADDRESS + + - **true**: **(Default)** The cluster attempts to communicate using the IP address specified. + - **false**: The cluster attempts to communicate using the hostname. + +Use IP address +~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E20

+ ++------------------------------------------------------------------------------+------------------------------------------------------------------------+ +| You can configure your high availability cluster-based deployment to | - System Config path: **Environment > High Availability** | +| communicate using the hostname instead of the IP address. | - ``config.json`` setting: ``".ClusterSettings.UseIPAddress: true",`` | +| | - Environment variable: ``MM_CLUSTERSETTINGS_USEIPADDRESS`` | +| - **true**: **(Default)** The cluster attempts to communicate | | +| using the IP address specified. | | +| - **false**: The cluster attempts to communicate using the | | +| hostname. | | ++------------------------------------------------------------------------------+------------------------------------------------------------------------+ + +.. config:setting:: ha-usegossip + :displayname: Use gossip (High Availability) + :systemconsole: Environment > High Availability + :configjson: .ClusterSettings.UseExperimentalGossip + :environment: MM_CLUSTERSETTINGS_USEEXPERIMENTALGOSSIP + + - **true**: **(Default)** The server attempts to communicate via the gossip protocol over the gossip port specified. + - **false**: The server attempts to communicate over the streaming port. + +Enable experimental gossip encryption +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E20

+ ++-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ +| Gossip encryption uses AES-256 by default, and this value isn’t | - System Config path: **Environment > High Availability** | +| configurable by design. | - ``config.json`` setting: ``".ClusterSettings.EnableExperimentalGossipEncryption: false”,`` | +| | - Environment variable: ``MM_CLUSTERSETTINGS_ENABLEEXPERIMENTALGOSSIPENCRYPTION`` | +| - **true**: **(Default for Cloud deployments)** | | +| All communication through the cluster using the gossip | | +| protocol will be encrypted. | | +| - **false**: **(Default for self-hosted deployments)** | | +| All communication using gossip protocol remains unchanged. | | +| protocol remains unencrypted. | | ++-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ +| **Note**: Alternatively, you can manually set the ``ClusterEncryptionKey`` row value in the **Systems** table. A key is a byte array converted to base64. | +| Set this value to either 16, 24, or 32 bytes to select AES-128, AES-192, or AES-256 respectively. | ++-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ + +.. config:setting:: ha-gossipcompression + :displayname: Enable gossip compression (High Availability) + :systemconsole: Environment > High Availability + :configjson: .ClusterSettings.EnableGossipCompression + :environment: MM_CLUSTERSETTINGS_ENABLEGOSSIPCOMPRESSION + + - **true**: **(Default)** All communication through the cluster uses gossip compression. + - **false**: All communication using the gossip protocol remains uncompressed. + +Enable gossip compression +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E20

+ ++-----------------------------------------------------------------+----------------------------------------------------------------------------------+ +| We recommend that you disable this configuration | - System Config path: **Environment > High Availability** | +| setting for better performance. | - ``config.json`` setting: ``".ClusterSettings.EnableGossipCompression: true”,`` | +| | - Environment variable: ``MM_CLUSTERSETTINGS_ENABLEGOSSIPCOMPRESSION`` | +| - **true**: **(Default for self-hosted deployments)** | | +| All communication through the cluster uses gossip | | +| compression. This setting is enabled by default to maintain | | +| compatibility with older servers. | | +| - **false**: **(Default for Cloud deployments)** | | +| All communication using the gossip protocol remains | | +| uncompressed. | | +| | | ++-----------------------------------------------------------------+----------------------------------------------------------------------------------+ + +.. config:setting:: ha-gossipport + :displayname: Gossip port (High Availability) + :systemconsole: Environment > High Availability + :configjson: .ClusterSettings.GossipPort + :environment: MM_CLUSTERSETTINGS_GOSSIPPORT + :description: The port used for the gossip protocol. Both UDP and TCP should be allowed on this port. Default value is **8074**. + +Gossip port +~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E20

+ ++-----------------------------------------------------------------+---------------------------------------------------------------------+ +| The port used for the gossip protocol. Both UDP and TCP | - System Config path: **Environment > High Availability** | +| should be allowed on this port. | - ``config.json`` setting: ``".ClusterSettings.GossipPort: 8074”,`` | +| | - Environment variable: ``MM_CLUSTERSETTINGS_GOSSIPPORT`` | +| Numerical input. Default is **8074**. | | ++-----------------------------------------------------------------+---------------------------------------------------------------------+ + +.. config:setting:: ha-readonlyconfig + :displayname: Read only config (High Availability) + :systemconsole: N/A + :configjson: .ClusterSettings.ReadOnlyConfig + :environment: MM_CLUSTERSETTINGS_READONLYCONFIG + :description: Configure whether changes made in the System Console are written to config.json or ignored. Default is ignored. + +Read only config +~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E20

+ ++-----------------------------------------------------------------+------------------------------------------------------------------------+ +| - **true**: **(Default)** Changes made to settings in the | - System Config path: N/A | +| System Console are ignored. | - ``config.json`` setting: ``".ClusterSettings.ReadOnlyConfig: true,`` | +| - **false**: Changes made to settings in the System Console | - Environment variable: ``MM_CLUSTERSETTINGS_READONLYCONFIG`` | +| are written to ``config.json``. | | ++-----------------------------------------------------------------+------------------------------------------------------------------------+ + +.. config:setting:: ha-networkinterface + :displayname: Network interface (High Availability) + :systemconsole: N/A + :configjson: .ClusterSettings.NetworkInterface + :environment: MM_CLUSTERSETTINGS_NETWORKINTERFACE + :description: An IP address used to identify the device that does automatic IP detection in high availability cluster-based deployments. + +Network interface +~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E20

+ ++-----------------------------------------------------------------+------------------------------------------------------------------------+ +| An IP address used to identify the device that does automatic | - System Config path: N/A | +| IP detection in high availability cluster-based deployments. | - ``config.json`` setting: ``".ClusterSettings.NetworkInterface: "",`` | +| | - Environment variable: ``MM_CLUSTERSETTINGS_NETWORKINTERFACE`` | +| String input. | | ++-----------------------------------------------------------------+------------------------------------------------------------------------+ + +.. config:setting:: ha-bindaddress + :displayname: Bind address (High Availability) + :systemconsole: N/A + :configjson: .ClusterSettings.BindAddress + :environment: MM_CLUSTERSETTINGS_BINDADDRESS + :description: An IP address used to bind cluster traffic to a specific network device. + +Bind address +~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E20

+ ++-----------------------------------------------------------------+--------------------------------------------------------------------+ +| An IP address used to bind cluster traffic to a specific | - System Config path: N/A | +| network device. | - ``config.json`` setting: ``".ClusterSettings.BindAddress: "",`` | +| | - Environment variable: ``MM_CLUSTERSETTINGS_BINDADDRESS`` | +| This setting is used primarily for servers with multiple | | +| network devices or different Bind Address and Advertise Address | | +| like in deployments that involve NAT (Network Address | | +| Translation). | | +| | | +| String input. | | ++-----------------------------------------------------------------+--------------------------------------------------------------------+ + +.. config:setting:: ha-advertiseaddress + :displayname: Advertise address (High Availability) + :systemconsole: N/A + :configjson: .ClusterSettings.AdvertiseAddress + :environment: MM_CLUSTERSETTINGS_ADVERTISEADDRESS + :description: The IP address used to access the server from other nodes. + +Advertise address +~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E20

+ ++-----------------------------------------------------------------+------------------------------------------------------------------------+ +| The IP address used to access the server from other nodes. | - System Config path: N/A | +| This settings is used primary when cluster nodes are not in | - ``config.json`` setting: ``".ClusterSettings.AdvertiseAddress: "",`` | +| the same network and involve NAT (Network Address Translation). | - Environment variable: ``MM_CLUSTERSETTINGS_ADVERTISEADDRESS`` | +| | | +| String input. | | ++-----------------------------------------------------------------+------------------------------------------------------------------------+ ---- @@ -114,8 +3293,351 @@ Logging .. include:: ../_static/badges/allplans-selfhosted.rst :start-after: :nosearch: -.. include:: logging-configuration-settings.rst - :start-after: :nosearch: +Configure logging by going to **System Console > Environment > Logging**, or by editing the ``config.json`` file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect. + +.. tip:: + + You can manage additional logging configuration within the ``config.json`` file specifically for Mattermost notifications under ``NotificationLogSettings``. These settings are equivalent to the configuration settings available under ``LogSettings``. + +.. config:setting:: log-enableconsole + :displayname: Output logs to console (Logging) + :systemconsole: Environment > Logging + :configjson: .LogSettings.EnableConsole + :environment: MM_LOGSETTINGS_ENABLECONSOLE + + - **true**: **(Default)** Output log messages are written to the console based on the `console log level <#console-log-level>`__ configuration. + - **false**: Output log messages aren’t written to the console. + +Output logs to console +~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++-----------------------------------------------+---------------------------------------------------------------------+ +| Configure Mattermost to output logs to the | - System Config path: **Environment > Logging** | +| console. | - ``config.json setting``: ``".LogSettings.EnableConsole": true",`` | +| | - Environment variable: ``MM_LOGSETTINGS_ENABLECONSOLE`` | +| - **true**: **(Default)** Output log messages | | +| are written to the console based on the | | +| `console log level <#console-log-level>`__ | | +| configuration. The server writes messages | | +| to the standard output stream (stdout). | | +| - **false**: Output log messages aren’t | | +| written to the console. | | ++-----------------------------------------------+---------------------------------------------------------------------+ + +.. config:setting:: log-consolelevel + :displayname: Console log level (Logging) + :systemconsole: Environment > Logging + :configjson: .LogSettings.ConsoleLevel + :environment: MM_LOGSETTINGS_CONSOLELEVEL + :description: The level of detail in log events written when Mattermost outputs log messages to the console. + + - **DEBUG**: **(Default)** Outputs verbose detail for developers debugging issues. + - **ERROR**: Outputs only error messages. + - **INFO**: Outputs error messages and information around startup and initialization. + +Console log level +~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++-----------------------------------------------+---------------------------------------------------------------------+ +| The level of detail in log events written | - System Config path: **Environment > Logging** | +| when Mattermost outputs log messages to the | - ``config.json setting``: ``".LogSettings.ConsoleLevel": DEBUG",`` | +| console. | - Environment variable: ``MM_LOGSETTINGS_CONSOLELEVEL`` | +| | | +| - **DEBUG**: **(Default)** Outputs verbose | | +| detail for developers debugging issues. | | +| - **ERROR**: Outputs only error messages. | | +| - **INFO**: Outputs error messages and | | +| information around startup and | | +| initialization. | | ++-----------------------------------------------+---------------------------------------------------------------------+ + +.. config:setting:: log-consolejson + :displayname: Output console logs as JSON (Logging) + :systemconsole: Environment > Logging + :configjson: .LogSettings.ConsoleJson + :environment: MM_LOGSETTINGS_CONSOLEJSON + :description: Configure Mattermost to output console logs as JSON. + + - **true**: **(Default)** Logged events are written in a machine-readable JSON format. + - **false**: Logged events are written in plain text. + +Output console logs as JSON +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++-----------------------------------------------+---------------------------------------------------------------------+ +| Configure Mattermost to output console logs | - System Config path: **Environment > Logging** | +| as JSON. | - ``config.json setting``: ``".LogSettings.ConsoleJson": true",`` | +| | - Environment variable: ``MM_LOGSETTINGS_CONSOLEJSON`` | +| - **true**: **(Default)** Logged events are | | +| written in a machine-readable JSON format. | | +| - **false**: Logged events are written in | | +| plain text. | | ++-----------------------------------------------+---------------------------------------------------------------------+ +| **Note**: Typically set to **true** in a production environment. | ++-----------------------------------------------+---------------------------------------------------------------------+ + +.. config:setting:: log-enableplaintextcolor + :displayname: Colorize plain text console logs (Logging) + :systemconsole: N/A + :configjson: .LogSettings.EnableColor + :environment: MM_LOGSETTINGS_ENABLECOLOR + :description: Enables system admins to display plain text log level details in color. + + - **true**: When logged events are output to the console as plain text, colorize log levels details. + - **false**: **(Default)** Plain text log details aren't colorized in the console. + +Colorize plain text console logs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++-----------------------------------------------+----------------------------------------------------------------------+ +| Enables system admins to display plain text | - System Config path: N/A | +| log level details in color. | - ``config.json setting``: ``".LogSettings.EnableColor": false",`` | +| | - Environment variable: ``MM_LOGSETTINGS_ENABLECOLOR`` | +| - **true**: When logged events are output to | | +| the console as plain text, colorize log | | +| levels details. | | +| - **false**: **(Default)** Plain text log | | +| details aren't colorized in the console. | | ++-----------------------------------------------+----------------------------------------------------------------------+ + +.. config:setting:: log-enablefile + :displayname: Output logs to file (Logging) + :systemconsole: Environment > Logging + :configjson: .LogSettings.EnableFile + :environment: MM_LOGSETTINGS_ENABLEFILE + :description: Configure Mattermost to output console logs to a file. + + - **true**: **(Default)** Logged events are written based on the `file log level <#file-log-level>`__ configuration to a ``mattermost.log`` file located in the directory configured via file location. + - **false**: Logged events aren’t written to a file. + +Output logs to file +~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++-----------------------------------------------+---------------------------------------------------------------------+ +| Configure Mattermost to output console logs | - System Config path: **Environment > Logging** | +| to a file. | - ``config.json setting``: ``".LogSettings.EnableFile": true",`` | +| | - Environment variable: ``MM_LOGSETTINGS_ENABLEFILE`` | +| - **true**: **(Default)** Logged events are | | +| written based on the | | +| `file log level <#file-log-level>`__ | | +| configuration to a ``mattermost.log`` file | | +| located in the directory configured via | | +| ``file location``. | | +| - **false**: Logged events aren’t written to | | +| a file. | | ++-----------------------------------------------+---------------------------------------------------------------------+ +| **Note**: Typically set to **true** in a production environment. When enabled, you can download the | +| ``mattermost.log`` file locally by going to **System Console > Reporting > Server Logs**, and selecting **Download | +| Logs**. | ++-----------------------------------------------+---------------------------------------------------------------------+ + +.. config:setting:: log-filelocation + :displayname: File log directory (Logging) + :systemconsole: Environment > Logging + :configjson: .LogSettings.FileLocation + :environment: MM_LOGSETTINGS_FILELOCATION + :description: The location of the log files. Default value is **./logs**. + +File log directory +~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++-----------------------------------------------+---------------------------------------------------------------------+ +| The location of the log files. | - System Config path: **Environment > Logging** | +| | - ``config.json setting``: ``".LogSettings.FileLocation": "",`` | +| String input. If left blank, log files are | - Environment variable: ``MM_LOGSETTINGS_FILELOCATION`` | +| stored in the ``./logs`` directory. | | ++-----------------------------------------------+---------------------------------------------------------------------+ +| **Note**: The path you configure must exist, and Mattermost must have write permissions for this directory. | ++-----------------------------------------------+---------------------------------------------------------------------+ + +.. config:setting:: log-filelevel + :displayname: File log level (Logging) + :systemconsole: Environment > Logging + :configjson: .LogSettings.FileLevel + :environment: MM_LOGSETTINGS_FILELEVEL + :description: The level of detail in log events when Mattermost outputs log messages to a file. + + - **DEBUG**: Outputs verbose detail for developers debugging issues. + - **ERROR**: Outputs only error messages. + - **INFO**: **(Default)** Outputs error messages and information around startup and initialization. + +File log level +~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++-----------------------------------------------+---------------------------------------------------------------------+ +| The level of detail in log events when | - System Config path: **Environment > Logging** | +| Mattermost outputs log messages to a file. | - ``config.json setting``: ``".LogSettings.FileLevel": INFO",`` | +| | - Environment variable: ``MM_LOGSETTINGS_FILELEVEL`` | +| - **DEBUG**: Outputs verbose detail for | | +| developers debugging issues. | | +| - **ERROR**: Outputs only error messages. | | +| - **INFO**: **(Default)** Outputs error | | +| messages and information around startup | | +| and initialization. | | ++-----------------------------------------------+---------------------------------------------------------------------+ + +.. config:setting:: log-filejson + :displayname: Output file logs as JSON (Logging) + :systemconsole: Environment > Logging + :configjson: .LogSettings.FileJson + :environment: MM_LOGSETTINGS_FILEJSON + :description: Configure Mattermost to output file logs as JSON. + + - **true**: **(Default)** Logged events are written in a machine-readable JSON format. + - **false**: Logged events are written in plain text. + +Output file logs as JSON +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++-----------------------------------------------+---------------------------------------------------------------------+ +| Configure Mattermost to output file logs as | - System Config path: **Environment > Logging** | +| JSON. | - ``config.json setting``: ``".LogSettings.FileJson": true",`` | +| | - Environment variable: ``MM_LOGSETTINGS_FILEJSON`` | +| - **true**: **(Default)** Logged events are | | +| written in a machine-readable JSON format. | | +| - **false**: Logged events are written in | | +| plain text. | | ++-----------------------------------------------+---------------------------------------------------------------------+ +| **Note**: Typically set to **true** in a production environment. | ++-----------------------------------------------+---------------------------------------------------------------------+ + +.. config:setting:: log-enablewebhookdebug + :displayname: Enable webhook debugging (Logging) + :systemconsole: Environment > Logging + :configjson: .LogSettings.EnableWebhookDebugging + :environment: MM_LOGSETTINGS_ENABLEWEBHOOKDEBUGGING + :description: Configure Mattermost to capture the contents of incoming webhooks to log files for debugging. + + - **true**: **(Default)** The contents of incoming webhooks are printed to console and/or file logs for debugging. + - **false**: The contents of incoming webhooks aren’t printed to log files. + +Enable webhook debugging +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++-----------------------------------------------+------------------------------------------------------------------------------+ +| Configure Mattermost to capture the contents | - System Config path: **Environment > Logging** | +| of incoming webhooks to console and/or file | - ``config.json setting``: ``".LogSettings.EnableWebhookDebugging": true",`` | +| logs for debugging. | - Environment variable: ``MM_LOGSETTINGS_ENABLEWEBHOOKDEBUGGING`` | +| | | +| - **true**: **(Default)** The contents of | | +| incoming webhooks are printed to log files | | +| for debugging. | | +| - **false**: The contents of incoming | | +| webhooks aren’t printed to log files. | | ++-----------------------------------------------+------------------------------------------------------------------------------+ +| **Note**: Enable debug logs by changing the :ref:`file log level ` to ``DEBUG`` to include | +| the request body of incoming webhooks in logs. | ++-----------------------------------------------+------------------------------------------------------------------------------+ + +.. config:setting:: log-multipletargetoutput + :displayname: Output logs to multiple targets (Logging) + :systemconsole: Environment > Logging + :configjson: .LogSettings.AdvancedLoggingJSON + :environment: MM_LOGSETTINGS_ADVANCEDLOGGINGJSON + :description: Configure Mattermost to allow any combination of console, local file, syslog, and TCP socket targets, and send log records to multiple targets. + +Output logs to multiple targets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++-----------------------------------------------+---------------------------------------------------------------------------+ +| Configure Mattermost to allow any combination | - System Config path: **Environment > Logging** | +| of console, local file, syslog, and TCP | - ``config.json setting``: ``".LogSettings.AdvancedLoggingJSON":: "",`` | +| socket targets, and send log records to | - Environment variable: ``MM_LOGSETTINGS_ADVANCEDLOGGINGJSON`` | +| multiple targets. | | +| | | +| String input can contain a filespec to | | +| another configuration file, a database DSN, | | +| or JSON. | | ++-----------------------------------------------+---------------------------------------------------------------------------+ +| **Notes**: | +| | +| - These targets have been chosen as they support the vast majority of log aggregators, and other log analysis tools, | +| without needing additional software installed. | +| - Logs are recorded asynchronously to reduce latency to the caller. | +| - Advanced logging supports hot-reloading of logger configuration. | ++-----------------------------------------------+---------------------------------------------------------------------------+ +| **Note**: See the :doc:`Mattermost logging ` documentation for details. | ++-----------------------------------------------+---------------------------------------------------------------------------+ + +.. config:setting:: log-maxfieldsize + :displayname: Maximum field size (Logging) + :systemconsole: N/A + :configjson: .LogSettings.MaxFieldSize + :environment: MM_LOGSETTINGS_MAXFIELDSIZE + :description: Enables system admins to limit the size of log fields during logging. Default is **2048**. + +Maximum field size +~~~~~~~~~~~~~~~~~~ + ++-----------------------------------------------+----------------------------------------------------------------------+ +| Enables system admins to limit the size of | - System Config path: N/A | +| log fields during logging. | - ``config.json setting``: ``".LogSettings.MaxFieldSize": 2048",`` | +| | - Environment variable: ``MM_LOGSETTINGS_MAXFIELDSIZE`` | +| Numerical value. Default is **2048**. | | ++-----------------------------------------------+----------------------------------------------------------------------+ + +.. config:setting:: log-enablediagnostics + :displayname: Enable diagnostics and error reporting (Logging) + :systemconsole: Environment > Logging + :configjson: .LogSettings.EnableDiagnostics + :environment: MM_LOGSETTINGS_ENABLEDIAGNOSTICS + :description: Send diagnostics and error reports to Mattermost, Inc. + +Enable diagnostics and error reporting +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++----------------------------------------------+-------------------------------------------------------------------------+ +| Whether or not diagnostics and error reports | - System Config path: **Environment > Logging** | +| are sent to Mattermost, Inc. | - ``config.json setting``: ``".LogSettings.EnableDiagnostics": "",`` | +| | - Environment variable: ``MM_LOGSETTINGS_ENABLEDIAGNOSTICS`` | +| - **true**: **(Default)** Send diagnostics | | +| and error reports. | | +| - **false**: Diagnostics and error reports | | +| aren't sent. | | ++----------------------------------------------+-------------------------------------------------------------------------+ +| **Note**: See the :ref:`telemetry ` docummentation for | +| details on the information Mattermost collects. | ++----------------------------------------------+-------------------------------------------------------------------------+ ---- @@ -125,8 +3647,203 @@ Session lengths .. include:: ../_static/badges/allplans-selfhosted.rst :start-after: :nosearch: -.. include:: session-lengths-configuration-settings.rst - :start-after: :nosearch: +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. + +.. config:setting:: sessionlength-extendwithactivity + :displayname: Extend session length with activity (Session Lengths) + :systemconsole: Environment > Session Lengths + :configjson: .ServiceSettings.ExtendSessionLengthWithActivity + :environment: MM_SERVICESETTINGS_EXTENDSESSONLENGTHWITHACTIVITY + + - **true**: **(Default)** Sessions are automatically extended when users are active in their Mattermost client. + - **false**: Sessions won't extend with activity in Mattermost. + +Extend session length with activity +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++----------------------------------------------------------------+-----------------------------------------------------------------------------------------+ +| Improves the user experience by extending sessions and keeping | - System Config path: **Environment > Session Lengths** | +| users logged in if they are active in their Mattermost apps. | - ``config.json`` setting: ``".ServiceSettings.ExtendSessionLengthWithActivity: true,`` | +| | - Environment variable: ``MM_SERVICESETTINGS_EXTENDSESSONLENGTHWITHACTIVITY`` | +| - **true**: **(Default)** Sessions are automatically | | +| extended when users are active in their Mattermost | | +| client. User sessions only expire when users aren’t active | | +| in their Mattermost client for the entire duration of the | | +| session lengths defined. | | +| - **false**: Sessions won't extend with activity in | | +| Mattermost. User sessions immediately expire at the | | +| end of the session length or based on the | | +| `session idle timeout <#session-idle-timeout>`__ configured. | | ++----------------------------------------------------------------+-----------------------------------------------------------------------------------------+ + +.. config:setting:: sessionlength-TerminateSessionsOnPasswordChange + :displayname: Terminate sessions on password change (Session Lengths) + :systemconsole: Environment > Session Lengths + :configjson: .ServiceSettings.TerminateSessionsOnPasswordChange + :environment: MM_SERVICESETTINGS_TERMINATESESSIONSONPASSWORDCHANGE + + - **true**: **(Default for new deployments)** Session revocation is enabled. All sessions of a user expire if their password is changed (by themselves or a system admin). If the password change is initiated by the user, their current session isn't terminated. + - **false**: **(Default for existing deployments)** Session revocation is disabled. When users change their password, only the user's current session is revoked. When a system admin changes the user's password, none of the user's sessions are revoked. + +Terminate sessions on password change +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++----------------------------------------------------------------+-------------------------------------------------------------------------------------------+ +| Enable or disable session revocation when a user's | - System Config path: **Environment > Session Lengths** | +| password changes. | - ``config.json`` setting: ``".ServiceSettings.TerminateSessionsOnPasswordChange: true,`` | +| | - Environment variable: ``MM_SERVICESETTINGS_TERMINATESESSIONSONPASSWORDCHANGE`` | +| - **true**: **(Default for new deployments)** | | +| Session revocation is enabled. | | +| All sessions of a user expire if their password is changed | | +| (by themselves or by a system admin). If the password change | | +| is initiated by the user, their current session isn't | | +| terminated. | | +| - **false**: **(Default for existing deployments)** | | +| Session revocation is disabled. | | +| When users change their password, only the user's current | | +| session is revoked. When a system admin changes the user's | | +| password, none of the user's sessions are revoked. | | ++----------------------------------------------------------------+-------------------------------------------------------------------------------------------+ + +.. config:setting:: sessionlength-webinhours + :displayname: Session length for AD/LDAP and email (Session Lengths) + :systemconsole: Environment > Session Lengths + :configjson: .ServiceSettings.SessionLengthWebInHours + :environment: MM_SERVICESETTINGS_SESSONLENGTHWEBINHOURS + + Set the number of hours counted from the last time a user entered their credentials into the web app or the desktop app to the expiry of the user’s session on email and AD/LDAP authentication. + Default is **720** hours. + +Session length for AD/LDAP and email +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++----------------------------------------------------------------+--------------------------------------------------------------------------------+ +| Set the number of hours counted from the last time a user | - System Config path: **Environment > Session Lengths** | +| entered their credentials into the web app or the desktop | - ``config.json`` setting: ``".ServiceSettings.SessionLengthWebInHours: 720,`` | +| app to the expiry of the user’s session on email and AD/LDAP | - Environment variable: ``MM_SERVICESETTINGS_SESSONLENGTHWEBINHOURS`` | +| authentication. | | +| | | +| Numerical input in hours. Default is **720** hours. | | ++----------------------------------------------------------------+--------------------------------------------------------------------------------+ +| **Note**: After changing this setting, the new session length takes effect after the next time the user enters their credentials. | ++----------------------------------------------------------------+--------------------------------------------------------------------------------+ + +.. config:setting:: sessionlength-mobileinhours + :displayname: Session length for mobile (Session Lengths) + :systemconsole: Environment > Session Lengths + :configjson: .ServiceSettings.SessionLengthMobileInHours + :environment: MM_SERVICESETTINGS_SESSONLENGTHMOBILEINHOURS + :description: Set the number of hours counted from the last time a user entered their credential into the mobile app to the expiry of the user’s session. Default is **720** hours. + +Session length for mobile +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++----------------------------------------------------------------+-----------------------------------------------------------------------------------+ +| Set the number of hours counted from the last time a user | - System Config path: **Environment > Session Lengths** | +| entered their credential into the mobile app to the expiry | - ``config.json`` setting: ``".ServiceSettings.SessionLengthMobileInHours: 720,`` | +| of the user’s session. | - Environment variable: ``MM_SERVICESETTINGS_SESSONLENGTHMOBILEINHOURS`` | +| | | +| Numerical input in hours. Default is **720** hours. | | ++----------------------------------------------------------------+-----------------------------------------------------------------------------------+ +| **Note**: After changing this setting, the new session length takes effect after the next time the user enters their credentials. | ++----------------------------------------------------------------+-----------------------------------------------------------------------------------+ + +.. config:setting:: sessionlength-ssoinhours + :displayname: Session length for SSO (Session Lengths) + :systemconsole: Environment > Session Lengths + :configjson: .ServiceSettings.SessionLengthSSOInHours + :environment: MM_SERVICESETTINGS_SESSONLENGTHSSOINHOURS + :description: Set the number of hours from the last time a user entered their SSO credentials to the expiry of the user’s session. Default is **720** hours. + +Session length for SSO +~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++----------------------------------------------------------------+----------------------------------------------------------------------------------+ +| Set the number of hours from the last time a user entered | - System Config path: **Environment > Session Lengths** | +| their SSO credentials to the expiry of the user’s session. | - ``config.json`` setting: ``".ServiceSettings.SessionLengthSSOInHours: 720,`` | +| This setting defines the session length for SSO | - Environment variable: ``MM_SERVICESETTINGS_SESSONLENGTHSSOINHOURS`` | +| authentication, such as SAML, GitLab, and OAuth 2.0. | | +| | | +| Numerical input in hours. Default is **720** hours. | | +| Numbers as decimals are also valid values for this | | +| configuration setting. | | ++----------------------------------------------------------------+----------------------------------------------------------------------------------+ +| **Notes**: | +| | +| - After changing this setting, the new session length takes effect after the next time the user enters their credentials. | +| - If the authentication method is SAML, GitLab, or OAuth 2.0, users may automatically be logged back in to Mattermost if they are already logged | +| in to SAML, GitLab, or with OAuth 2.0. | ++----------------------------------------------------------------+----------------------------------------------------------------------------------+ + +.. config:setting:: sessionlength-sessioncache + :displayname: Session cache (Session Lengths) + :systemconsole: Environment > Session Lengths + :configjson: .ServiceSettings.SessionCacheInMinutes + :environment: MM_SERVICESETTINGS_SESSONCACHEINMINUTES + :description: Set the number of minutes to cache a session in memory. Default is **10** minutes. + +Session cache +~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++----------------------------------------------------------------+-----------------------------------------------------------------------------+ +| Set the number of minutes to cache a session in memory. | - System Config path: **Environment > Session Lengths** | +| | - ``config.json`` setting: ``".ServiceSettings.SessionCacheInMinutes: 10,`` | +| Numerical input in minutes. Default is **10** minutes. | - Environment variable: ``MM_SERVICESETTINGS_SESSONCACHEINMINUTES`` | ++----------------------------------------------------------------+-----------------------------------------------------------------------------+ + +.. config:setting:: sessionlength-sessionidletimeout + :displayname: Session idle timeout (Session Lengths) + :systemconsole: N/A + :configjson: .ServiceSettings.SessionIdleTimeoutInMinutes + :environment: MM_SERVICESETTINGS_SESSONIDLETIMEOUTINMINUTES + + The number of minutes from the last time a user was active on the system to the expiry of the user’s session. Once expired, the user will need to log in to continue. + Default is **43200** minutes (30 days). Minimum value is 5 minutes, and a value of 0 sets the time as unlimited. + +Session idle timeout +~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++----------------------------------------------------------------+--------------------------------------------------------------------------------------+ +| The number of minutes from the last time a user was active | - System Config path: N/A | +| on the system to the expiry of the user’s session. | - ``config.json`` setting: ``".ServiceSettings.SessionIdleTimeoutInMinutes: 43200,`` | +| Once expired, the user will need to log in to continue. | - Environment variable: ``MM_SERVICESETTINGS_SESSONIDLETIMEOUTINMINUTES`` | +| | | +| Numerical input in minutes. Default is **43200** (30 days). | | +| Minimum value is **5** minutes, and a value of **0** sets | | +| the time as unlimited. | | ++----------------------------------------------------------------+--------------------------------------------------------------------------------------+ +| **Notes**: | +| | +| - This setting has no effect when `extend session length with activity <#extend-session-length-with-activity>`__ is set to **true**. | +| - This setting applies to the webapp and the desktop app. For mobile apps, use an | +| :doc:`EMM provider ` to lock the app when not in use. | +| - In :doc:`high availability mode `, enable IP hash load balancing for reliable | +| timeout measurement. | ++----------------------------------------------------------------+--------------------------------------------------------------------------------------+ ---- @@ -136,8 +3853,57 @@ Performance monitoring .. include:: ../_static/badges/ent-selfhosted.rst :start-after: :nosearch: -.. include:: performance-monitoring-configuration-settings.rst - :start-after: :nosearch: +Configure performance monitoring by going to **System Console > Environment > Performance Monitoring**, or by editing the ``config.json`` file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect. + +.. config:setting:: perf-enablemonitoring + :displayname: Enable performance monitoring (Performance Monitoring) + :systemconsole: Environment > Performance Monitoring + :configjson: .MetricsSettings.Enable + :environment: MM_METRICSSETTINGS_ENABLE + :description: Enable or disable performance monitoring. + + - **true**: Performance monitoring data collection and profiling is enabled. + - **false**: **(Default)** Mattermost performance monitoring is disabled. + +Enable performance monitoring +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E20

+ ++-----------------------------------------------+---------------------------------------------------------------------+ +| Enable or disable performance monitoring. | - System Config path: **Environment > Performance Monitoring** | +| | - ``config.json setting``: ``".MetricsSettings.Enable": false",`` | +| - **true**: Performance monitoring data | - Environment variable: ``MM_METRICSSETTINGS_ENABLE`` | +| collection and profiling is enabled. | | +| - **false**: **(Default)** Mattermost | | +| performance monitoring is disabled. | | ++-----------------------------------------------+---------------------------------------------------------------------+ +| See the :doc:`performance monitoring ` documentation | +| to learn more. | ++-----------------------------------------------+---------------------------------------------------------------------+ + +.. config:setting:: perf-listenaddress + :displayname: Listen address for performance (Performance Monitoring) + :systemconsole: Environment > Performance Monitoring + :configjson: .MetricsSettings.ListenAddress + :environment: MM_METRICSSETTINGS_LISTENADDRESS + :description: The port the Mattermost server will listen on to expose performance metrics, when enabled. Default is port **8067**. + +Listen address for performance +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E20

+ ++---------------------------------------------------------------+-------------------------------------------------------------------------+ +| The port the Mattermost server will listen on to expose | - System Config path: **Environment > Performance Monitoring** | +| performance metrics, when enabled. | - ``config.json setting``: ``".MetricsSettings.ListenAddress": 8067",`` | +| | - Environment variable: ``MM_METRICSSETTINGS_LISTENADDRESS`` | +| Numerical input. Default is **8067**. | | ++---------------------------------------------------------------+-------------------------------------------------------------------------+ ---- @@ -147,8 +3913,153 @@ Developer .. include:: ../_static/badges/allplans-selfhosted.rst :start-after: :nosearch: -.. include:: developer-mode-configuration-settings.rst - :start-after: :nosearch: +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. + +.. config:setting:: dev-enabletesting + :displayname: Enable testing commands (Developer) + :systemconsole: Environment > Developer + :configjson: .ServiceSettings.EnableTesting + :environment: MM_SERVICESETTINGS_ENABLETESTING + :description: Enable or disable the ``/test`` slash command. + + - **true**: **(Default)** The ``/test`` slash command is enabled to load test accounts and test data. + - **false**: The ``/test`` slash command is disabled. + +Enable testing commands +~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------+--------------------------------------------------------------------------+ +| Enable or disable the ``/test`` slash command. | - System Config path: **Environment > Developer** | +| | - ``config.json setting``: ``".ServiceSettings.EnableTesting": true",`` | +| - **true**: **(Default)** The ``/test`` slash | - Environment variable: ``MM_SERVICESETTINGS_ENABLETESTING`` | +| command is enabled to load test accounts | | +| and test data. | | +| - **false**: The ``/test`` slash command is | | +| disabled. | | ++---------------------------------------------------+--------------------------------------------------------------------------+ + +.. config:setting:: dev-enabledeveloper + :displayname: Enable developer mode (Developer) + :systemconsole: Environment > Developer + :configjson: .ServiceSettings.EnableDeveloper + :environment: MM_SERVICESETTINGS_ENABLEDEVELOPER + :description: Enable or disable developer mode. + + - **true**: **(Default)** Javascript errors are shown in a banner at the top of Mattermost the user interface. Not recommended for use in production. + - **false**: Users are not alerted to Javascript errors. + +Enable developer mode +~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++-----------------------------------------------+---------------------------------------------------------------------------+ +| Enable or disable developer mode. | - System Config path: **Environment > Developer** | +| | - ``config.json setting``: ``".ServiceSettings.EnableDeveloper": true",`` | +| - **true**: **(Default)** Javascript errors | - Environment variable: ``MM_SERVICESETTINGS_ENABLEDEVELOPER`` | +| are shown in a banner at the top of | | +| Mattermost the user interface. | | +| Not recommended for use in production. | | +| - **false**: Users are not alerted to | | +| Javascript errors. | | ++-----------------------------------------------+---------------------------------------------------------------------------+ + +.. config:setting:: dev-enableclientdebugging + :displayname: Enable client debugging (Developer) + :systemconsole: Environment > Developer + :configjson: .ServiceSettings.EnableClientPerformanceDebugging + :environment: MM_SERVICESETTINGS_ENABLECLIENTPERFORMANCEDEBUGGING + :description: Enable or disable client-side debugging settings found in *Settings > Advanced > Debugging* for individual users. + + - **true**: Those settings are visible and can be enabled by users. + - **false**: **(Default)** Those settings are hidden and disabled. + +Enable client debugging +~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++---------------------------------------------------+---------------------------------------------------------------------------------------------+ +| Enable or disable client-side debugging settings | - System Config path: **Environment > Developer** | +| found in **Settings > Advanced > Debugging** | - ``config.json setting``: ``".ServiceSettings.EnableClientPerformanceDebugging": false",`` | +| for individual users. | - Environment variable: ``MM_SERVICESETTINGS_ENABLECLIENTPERFORMANCEDEBUGGING`` | +| | | +| - **true**: Those settings are visible and can | | +| be enabled by users. | | +| - **false**: **(Default)** Those settings are | | +| hidden and disabled. | | ++---------------------------------------------------+---------------------------------------------------------------------------------------------+ +| See the :ref:`client debugging ` documentation to learn more. | ++---------------------------------------------------+---------------------------------------------------------------------------------------------+ + +.. config:setting:: dev-allowuntrustedinternalconnections + :displayname: Allow untrusted internal connections (Developer) + :systemconsole: Environment > Developer + :configjson: .ServiceSettings.AllowedUntrustedInternalConnections + :environment: MM_SERVICESETTINGS_ALLOWUNTRUSTEDINTERNALCONNECTIONS + :description: This setting is a whitelist of local network addresses that can be requested by the Mattermost server. + +Allow untrusted internal connections +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + +

Also available in legacy Mattermost Enterprise Edition E10 or E20

+ ++-----------------------------------------------+-----------------------------------------------------------------------------------------------+ +| Limit the ability for the Mattermost server | - System Config path: **Environment > Developer** | +| to make untrusted requests within its local | - ``config.json setting``: ``".ServiceSettings.AllowedUntrustedInternalConnections": "",`` | +| network. A request is considered “untrusted” | - Environment variable: ``MM_SERVICESETTINGS_ALLOWEDUNTRUSTEDINTERNALCONNECTIONS`` | +| when it’s made on behalf of a client. | | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------+ +| This setting is a whitelist of local network addresses that can be requested by the Mattermost server. It’s configured as a | +| whitespace-separated list of hostnames, IP addresses, and CIDR ranges that can be accessed. | +| | +| Requests that can only be configured by system admins are considered trusted and won't be affected by this setting. Trusted URLs include | +| ones used for OAuth login or for sending push notifications. | +| | +| The following features make untrusted requests and are affected by this setting: | +| | +| - Integrations using webhooks, slash commands, or message actions. This prevents them from requesting endpoints within the local network. | +| - Link previews. When a link to a local network address is posted in a chat message, this prevents a link preview from being displayed. | +| - The local :doc:`image proxy `. If the local image proxy is enabled, images located on | +| the local network cannot be used by integrations or posted in chat messages. | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------+ +| | +| Some examples of when you may want to modify this setting include: | +| | +| - When installing a plugin that includes its own images, such as `Matterpoll `__, you'll need to | +| add the Mattermost server’s domain name to | +| this list. | +| - When running a bot or webhook-based integration on your local network, you’ll need to add the hostname of the bot/integration to this list. | +| - If your network is configured in such a way that publicly-accessible web pages or images are accessed by the Mattermost server using | +| their internal IP address, the hostnames for those servers must be added to this list. | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------+ +| **Warning**: This setting is intended to prevent users located outside your local network from using the Mattermost server to request | +| confidential data from inside your network. Care should be used when configuring this setting to prevent unintended access to your local | +| network. | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------+ +| **Notes**: | +| | +| - The public IP of the Mattermost application server itself is also considered a reserved IP. | +| - Use whitespaces instead of commas to list the hostnames, IP addresses, or CIDR ranges. | +| For example: ``webhooks.internal.example.com``, ``127.0.0.1``, or ``10.0.16.0/28``. | +| - IP address and domain name rules are applied before host resolution. | +| - CIDR rules are applied after host resolution, and only CIDR rules require DNS resolution. | +| - Mattermost attempts to match IP addresses and hostnames without even resolving. If that fails, Mattermost resolve using the local resolver | +| (by reading the ``/etc/hosts`` file first), then checking for matching CIDR rules. | +| For example, if the domain “webhooks.internal.example.com” resolves to the IP address ``10.0.16.20``, a webhook with the URL | +| ``https://webhooks.internal.example.com/webhook`` can be whitelisted using ``webhooks.internal.example.com``, or ``10.0.16.16/28``, | +| but not ``10.0.16.20``. | ++-----------------------------------------------+-----------------------------------------------------------------------------------------------+ config.json-only settings ------------------------- diff --git a/source/configure/experimental-configuration-settings.rst b/source/configure/experimental-configuration-settings.rst index 6f11faf1629..d737dc96a97 100644 --- a/source/configure/experimental-configuration-settings.rst +++ b/source/configure/experimental-configuration-settings.rst @@ -1001,8 +1001,12 @@ 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. -.. include:: common-config-settings-notation.rst - :start-after: :nosearch: +.. 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``. .. config:setting:: exp-allowedthemes :displayname: Allowed themes (Experimental) @@ -1846,7 +1850,7 @@ This setting isn't available in the System Console and can only be set in ``conf +------------------------------------------------------------------------------------------------+ .. note:: - This is a client only override that doesn't affect the listening port of the server process which is controlled by the :ref:`Web server listen address ` setting. + This is a client only override that doesn't affect the listening port of the server process which is controlled by the :ref:`Web server listen address ` setting. .. config:setting:: exp-websocketport :displayname: Websocket port (Experimental) @@ -1867,7 +1871,7 @@ This setting isn't available in the System Console and can only be set in ``conf +----------------------------------------------------------------------------------------+ .. note:: - This is a client only override that doesn't affect the listening port of the server process which is controlled by the :ref:`Web server listen address ` setting. + This is a client only override that doesn't affect the listening port of the server process which is controlled by the :ref:`Web server listen address ` setting. .. config:setting:: exp-enableopentracing :displayname: Enable OpenTracing (Experimental) diff --git a/source/configure/file-storage-configuration-settings.rst b/source/configure/file-storage-configuration-settings.rst deleted file mode 100644 index da064f75138..00000000000 --- a/source/configure/file-storage-configuration-settings.rst +++ /dev/null @@ -1,515 +0,0 @@ -:orphan: -:nosearch: - -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. - -.. include:: ../_static/badges/academy-file-storage.rst - :start-after: :nosearch: - -.. note:: - - Mattermost currently supports storing files on the local filesystem and Amazon S3 or S3-compatible containers. We have tested Mattermost with `MinIO `__ and `Digital Ocean Spaces `__ products, but not all S3-compatible containers on the market. If you are looking to use other S3-compatible containers, we recommend completing your own testing. - -.. config:setting:: file-storagesystem - :displayname: File storage system (File Storage) - :systemconsole: Environment > File Storage - :configjson: .FileSettings.DriverName - :environment: MM_FILESETTINGS_DRIVERNAME - :description: The type of file storage system used. - - - **local**: **(Default)** Files and images are stored in the specified local file directory. - - **amazons3**: Files and images are stored on Amazon S3 based on the access key, bucket, and region fields provided. - -File storage system -~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| The type of file storage system used. | - System Config path: **Environment > File Storage** | -| Can be either Local File System or Amazon S3. | - ``config.json`` setting: ``".FileSettings.DriverName: local”,`` | -| | - Environment variable: ``MM_FILESETTINGS_DRIVERNAME`` | -| - **local**: **(Default)** Files and images are stored in | | -| the specified local file directory. | | -| - **amazons3**: Files and images are stored on Amazon S3 | | -| based on the access key, bucket, and region fields | | -| provided. The driver is compatible with MinIO (Beta) | | -| and Digital Ocean Spaces. | | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ - -.. config:setting:: file-localstoragedirectory - :displayname: Local storage directory (File Storage) - :systemconsole: Environment > File Storage - :configjson: .FileSettings.Directory - :environment: MM_FILESETTINGS_DIRECTORY - :description: The local directory to which files are written when the **File storage system** is set to **local**. Default value is **./data/**. - -Local storage directory -~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| The local directory to which files are written when the | - System Config path: **Environment > File Storage** | -| **File storage system** is set to **local**. | - ``config.json`` setting: ``".FileSettings.Directory”,`` | -| Can be any directory writable by the user Mattermost is | - Environment variable: ``MM_FILESETTINGS_DIRECTORY`` | -| running as, and is relative to the directory where | | -| Mattermost is installed. | | -| | | -| Defaults to **./data/**. | | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| **Note**: When **File storage system** is set to **amazons3**, this setting has no effect. | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ - -.. config:setting:: file-maxfilesize - :displayname: Maximum file size (File Storage) - :systemconsole: Environment > File Storage - :configjson: .FileSettings.MaxFileSize - :environment: MM_FILESETTINGS_MAXFILESIZE - :description: The maximum file size, in bytes, for message attachments and plugin uploads. Default value is **104857600** bytes (100 mebibytes). - -Maximum file size -~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+-------------------------------------------------------------------+--------------------------------------------------------------------------+ -| The maximum file size for message attachments and plugin | - System Config path: **Environment > File Storage** | -| uploads. This value must be specified in mebibytes in the | - ``config.json`` setting: ``".FileSettings.MaxFileSize: 104857600",`` | -| System Console, and in bytes in the ``config.json`` file. | - Environment variable: ``MM_FILESETTINGS_MAXFILESIZE`` | -| | | -| The default is ``104857600`` bytes (**100** mebibytes). | | -+-------------------------------------------------------------------+--------------------------------------------------------------------------+ -| **Warning**: Verify server memory can support your setting choice. Large file sizes increase the risk of server crashes and failed | -| uploads due to network disruptions. | -+-------------------------------------------------------------------+--------------------------------------------------------------------------+ -| **Notes**: | -| | -| - When :ref:`uploading plugin files `, a ``Received invlaid response from | -| the server`` error typically indicates that ``MaxFileSize`` isn't large enough to support the plugin file upload, and/or that proxy | -| settings may not be sufficient. | -| - If you use a proxy or load balancer in front of Mattermost, the following proxy settings must be adjusted accordingly: | -| | -| - For NGINX, use ``client_max_body_size``. | -| - For Apache use ``LimitRequestBody``. | -+-------------------------------------------------------------------+--------------------------------------------------------------------------+ - -.. config:setting:: file-enabledocsearchbycontent - :displayname: Enable document search by content (File Storage) - :systemconsole: Environment > File Storage - :configjson: .FileSettings.ExtractContent - :environment: MM_FILESETTINGS_EXTRACTCONTENT - :description: Enable users to search the contents of documents attached to messages. - - - **true**: **(Default)** Documents are searchable by their content. - - **false**: Documents aren’t searchable by their content. - -Enable document search by content -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| Enable users to search the contents of documents attached | - System Config path: **Environment > File Storage** | -| to messages. | - ``config.json`` setting: ``".FileSettings.ExtractContent: true",`` | -| | - Environment variable: ``MM_FILESETTINGS_EXTRACTCONTENT`` | -| - **true**: **(Default)** Documents are searchable by | | -| their content. | | -| - **false**: Documents aren’t searchable by their content. | | -| When document content search is disabled, users can search | | -| for files by file name only. | | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ -| **Note**: Document content search results for files shared before upgrading to Mattermost Server v5.35 may be incomplete until an | -| extraction command is executed using the :ref:`mmctl `. | -| If this command is not run, users can search older files based on file name only. | -| | -| You can optionally install the following `dependencies `__ to extend content searching support in | -| Mattermost to include file formats beyond PDF, DOCX, and ODT, such as DOC, RTF, XML, and HTML: | -| | -| - **tidy**: Used to search the contents of HTML documents. | -| - **wv**: Used to search the contents of DOC documents. | -| - **popplerutils**: Used to significantly improve server performance when extracting the contents of PDF documents. | -| - **unrtf**: Used to search the contents of RTF documents. | -| - **JusText**: Used to search HTML documents. | -| | -| If you choose not to install these dependencies, you’ll see log entries for documents that couldn’t be extracted. | -| Any documents that can’t be extracted are skipped and logged so that content extraction can proceed. | -+---------------------------------------------------------------+-------------------------------------------------------------------------------------+ - -.. config:setting:: file-enabledocsearchwithinzipfile - :displayname: Enable searching content of documents within ZIP files (File Storage) - :systemconsole: Environment > File Storage - :configjson: .FileSettings.ArchiveRecursion - :environment: MM_FILESETTINGS_ARCHIVERECURSION - :description: Enables users to search the contents of compressed ZIP files attached to messages. - - - **true**: Contents of documents within ZIP files are returned in search results. - - **false**: **(Default)** The contents of documents within ZIP files aren’t returned in search results. - -Enable searching content of documents within ZIP files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+----------------------------------------------------------------------------------------+ -| Enables users to search the contents of compressed ZIP files | - System Config path: **Environment > File Storage** | -| attached to messages. | - ``config.json`` setting: ``".FileSettings.ArchiveRecursion: false",`` | -| | - Environment variable: ``MM_FILESETTINGS_ARCHIVERECURSION`` | -| - **true**: Contents of documents within ZIP files are | | -| returned in search results. This may have an impact on | | -| server performance for large files. | | -| the specified local file directory. | | -| - **false**: **(Default)** The contents of documents within | | -| ZIP files aren’t returned in search results. | | -+---------------------------------------------------------------+----------------------------------------------------------------------------------------+ -| **Note**: Document content search within ZIP files is available, with mobile support coming soon. | -| Searching document contents adds load to your server. For large deployments, or teams that share many large, text-heavy documents, | -| we recommend you review our :ref:`hardware requirements `, | -| and test enabling this feature in a staging environment before enabling it in a production environment. | -+---------------------------------------------------------------+----------------------------------------------------------------------------------------+ - -.. config:setting:: file-s3bucket - :displayname: Amazon S3 bucket (File Storage) - :systemconsole: Environment > File Storage - :configjson: .FileSettings.AmazonS3Bucket - :environment: MM_FILESETTINGS_AMAZONS3BUCKET - :description: The name of the bucket for your S3-compatible object storage instance. - -Amazon S3 bucket -~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| The name of the bucket for your S3-compatible object | - System Config path: **Environment > File Storage** | -| storage instance. | - ``config.json`` setting: ``".FileSettings.AmazonS3Bucket",`` | -| | - Environment variable: ``MM_FILESETTINGS_AMAZONS3BUCKET`` | -| A string with the S3-compatible bucket name. | | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ - -.. config:setting:: file-s3pathprefix - :displayname: Amazon S3 path prefix (File Storage) - :systemconsole: N/A - :configjson: .FileSettings.AmazonS3PathPrefix - :environment: MM_FILESETTINGS_AMAZONS3PATHPREFIX - :description: The prefix you selected for your **Amazon S3 bucket** in AWS. - -Amazon S3 path prefix -~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| The prefix you selected for your **Amazon S3 bucket** in AWS. | - System Config path: N/A | -| | - ``config.json`` setting: ``".FileSettings.AmazonS3PathPrefix",`` | -| A string containing the path prefix. | - Environment variable: ``MM_FILESETTINGS_AMAZONS3PATHPREFIX`` | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ - -.. config:setting:: file-s3region - :displayname: Amazon S3 region (File Storage) - :systemconsole: Environment > File Storage - :configjson: .FileSettings.AmazonS3Region - :environment: MM_FILESETTINGS_AMAZONS3REGION - :description: The AWS region you selected when creating your **Amazon S3 bucket** in AWS. For MinIO or Digital Ocean Spaces, leave this setting empty. - -Amazon S3 region -~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| The AWS region you selected when creating your | - System Config path: **Environment > File Storage** | -| **Amazon S3 bucket** in AWS. | - ``config.json`` setting: ```".FileSettings.AmazonS3Region",`` | -| | - Environment variable: ``MM_FILESETTINGS_AMAZONS3REGION`` | -| A string with the AWS region containing the bucket. | | -| If no region is set, Mattermost attempts to get the | | -| appropriate region from AWS, and sets it to **us-east-1** | | -| if none found. | | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| **Note**: For MinIO or Digital Ocean Spaces, leave this setting empty. | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ - -.. config:setting:: file-s3accesskeyid - :displayname: Amazon S3 access key ID (File Storage) - :systemconsole: Environment > File Storage - :configjson: .FileSettings.AmazonS3AccessKeyId - :environment: MM_FILESETTINGS_AMAZONS3ACCESSKEYID - :description: A string with the access key for the S3-compatible storage instance. - -Amazon S3 access key ID -~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| A string with the access key for the S3-compatible storage | - System Config path: **Environment > File Storage** | -| instance. Your EC2 administrator can supply you with the | - ``config.json`` setting: ``".FileSettings.AmazonS3AccessKeyId",`` | -| Access Key ID. | - Environment variable: ``MM_FILESETTINGS_AMAZONS3ACCESSKEYID`` | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| **Note**: This is required for access unless you are using an | -| `Amazon S3 IAM Role `__ with | -| Amazon S3. | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ - -.. config:setting:: file-s3endpoint - :displayname: Amazon S3 endpoint (File Storage) - :systemconsole: Environment > File Storage - :configjson: .FileSettings.AmazonS3Endpoint - :environment: MM_FILESETTINGS_AMAZONS3ENDPOINT - :description: The hostname of your S3-compatible instance. Default value is **s3.amazonaws.com**. - -Amazon S3 endpoint -~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+------------------------------------------------------------------------------------+ -| The hostname of your S3-compatible instance. | - System Config path: **Environment > File Storage** | -| | - ``config.json`` setting: ``".FileSettings.AmazonS3Endpoint: s3.amazonaws.com",`` | -| A string with the hostname of the S3-compatible storage | - Environment variable: ``MM_FILESETTINGS_AMAZONS3ENDPOINT`` | -| instance. Defaults to **s3.amazonaws.com**. | | -+---------------------------------------------------------------+------------------------------------------------------------------------------------+ -| **Note**: For Digital Ocean Spaces, the hostname should be set to **.digitaloceanspaces.com**, where **** is the abbreviation | -| for the region you selected when setting up the Space. It can be **nyc3**, **ams3**, or **sgp1**. | -+---------------------------------------------------------------+------------------------------------------------------------------------------------+ - -.. config:setting:: file-s3secretaccesskey - :displayname: Amazon S3 secret access key (File Storage) - :systemconsole: Environment > File Storage - :configjson: .FileSettings.AmazonS3SecretAccessKey - :environment: MM_FILESETTINGS_AMAZONS3SECRETACCESSKEY - :description: The secret access key associated with your Amazon S3 Access Key ID. - -Amazon S3 secret access key -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| The secret access key associated with your Amazon S3 | - System Config path: **Environment > File Storage** | -| Access Key ID. | - ``config.json`` setting: ``".FileSettings.AmazonS3SecretAccessKey",`` | -| | - Environment variable: ``MM_FILESETTINGS_AMAZONS3SECRETACCESSKEY`` | -| A string with the secret access key for the S3-compatible | | -| storage instance. | | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ - -.. config:setting:: file-s3secureconnection - :displayname: Enable secure Amazon S3 connections (File Storage) - :systemconsole: Environment > File Storage - :configjson: .FileSettings.AmazonS3SSL - :environment: MM_FILESETTINGS_AMAZONS3SSL - :description: Enable or disable secure Amazon S3 connections. Default value is **true**. - -Enable secure Amazon S3 connections -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| Enable or disable secure Amazon S3 connections. | - System Config path: **Environment > File Storage** | -| | - ``config.json`` setting: ``".FileSettings.AmazonS3SSL: true",`` | -| - **true**: **(Default)** Enables only secure Amazon | - Environment variable: ``MM_FILESETTINGS_AMAZONS3SSL`` | -| S3 connections. | | -| - **false**: Allows insecure connections to Amazon S3. | | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ - -.. config:setting:: file-s3signv2 - :displayname: Amazon S3 signature v2 (File Storage) - :systemconsole: N/A - :configjson: .FileSettings.AmazonS3SignV2 - :environment: MM_FILESETTINGS_AMAZONS3SIGNV2 - - - **true**: Use Signature v2 signing process. - - **false**: **(Default)** Use Signature v4 signing process. - -Amazon S3 signature v2 -~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Not available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| By default, Mattermost uses Signature v4 to sign API calls | - System Config path: N/A | -| to AWS, but under some circumstances, v2 is required. | - ``config.json`` setting: ``".FileSettings.AmazonS3SignV2: false",`` | -| | - Environment variable: ``MM_FILESETTINGS_AMAZONS3SIGNV2`` | -| - **true**: Use Signature v2 signing process. | | -| - **false**: **(Default)** Use Signature v4 signing process. | | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| See the `AWS `__ documentation for information about when to | -| use the Signature v2 signing process. | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ - -.. config:setting:: file-s3sse - :displayname: Enable server-side encryption for Amazon S3 (File Storage) - :systemconsole: Environment > File Storage - :configjson: .FileSettings.AmazonS3SSE - :environment: MM_FILESETTINGS_AMAZONS3SSE - - - **true**: Encrypts files in Amazon S3 using server-side encryption with Amazon S3-managed keys. - - **false**: **(Default)** Doesn’t encrypt files in Amazon S3. - -Enable server-side encryption for Amazon S3 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E20

- -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| Enable server-side encryption for Amazon S3. | - System Config path: **Environment > File Storage** | -| | - ``config.json`` setting: ``".FileSettings.AmazonS3SSE: false",`` | -| - **true**: Encrypts files in Amazon S3 using server-side | - Environment variable: ``MM_FILESETTINGS_AMAZONS3SSE`` | -| encryption with Amazon S3-managed keys. | | -| - **false**: **(Default)** Doesn’t encrypt files in | | -| Amazon S3. | | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ - -.. config:setting:: file-s3trace - :displayname: Enable Amazon S3 debugging (File Storage) - :systemconsole: Environment > File Storage - :configjson: .FileSettings.AmazonS3Trace - :environment: MM_FILESETTINGS_AMAZONS3TRACE - - - **true**: Log additional debugging information is logged to the system logs. - - **false**: **(Default)** No Amazon S3 debugging information is included in the system logs. - -Enable Amazon S3 debugging -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| Enable or disable Amazon S3 debugging to capture additional | - System Config path: **Environment > File Storage** | -| debugging information in system logs | - ``config.json`` setting: ``".FileSettings.AmazonS3Trace: false",`` | -| | - Environment variable: ``MM_FILESETTINGS_AMAZONS3TRACE`` | -| - **true**: Log additional debugging information is logged | | -| to the system logs. | | -| - **false**: **(Default)** No Amazon S3 debugging information | | -| is included in the system logs. Typically set to **false** | | -| in production. | | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| Select the **Test Connection** button in the System Console to validate the settings and ensure the user can access the server. | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ - -.. config:setting:: file-amazons3requesttimeoutmilliseconds - :displayname: Amazon S3 request timeout (File Storage) - :systemconsole: N/A - :configjson: .FileSettings.AmazonS3RequestTimeoutMilliseconds - :environment: MM_FILESETTINGS_AMAZONS3REQUESTTIMEOUTMILLISECONDS - :description: Amount of time, in milliseconds, before requests to Amazon S3 time out. Default value is 30000 (30 seconds). - -Amazon S3 request timeout -~~~~~~~~~~~~~~~~~~~~~~~~~ - -+---------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| The amount of time, in milliseconds, before requests to | - System Config path: N/A | -| Amazon S3 storage time out. | - ``config.json`` setting: ``".FileSettings.AmazonS3RequestTimeoutMilliseconds: 30000`` | -| | - Environment variable: ``MM_FILESETTINGS_AMAZONS3REQUESTTIMEOUTMILLISECONDS`` | -| Default is 30000 (30 seconds). | | -+---------------------------------------------------------------+-----------------------------------------------------------------------------------------+ - -.. config:setting:: file-amazons3uploadpartsizebytes - :displayname: Amazon S3 upload part size (File Storage) - :systemconsole: N/A - :configjson: .FileSettings.AmazonS3UploadPartSizeBytes - :environment: MM_FILESETTINGS_AMAZONS3UPLOADPARTSIZEBYTES - :description: The size, in bytes, of each part in a multi-part upload to Amazon S3. Default value is 5242880 (5MB). - -Amazon S3 upload part size -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -+---------------------------------------------------------------+---------------------------------------------------------------------------------------+ -| The size, in bytes, of each part in a multi-part | - System Config path: N/A | -| upload to Amazon S3. | - ``config.json`` setting: ``".FileSettings.AmazonS3UploadPartSizeBytes: 5242880`` | -| | - Environment variable: ``MM_FILESETTINGS_AMAZONS3UPLOADPARTSIZEBYTES`` | -| Numeric value. Default is 5242880 (5MB). | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------+ -| **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. | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------+ - -.. config:setting:: file-exportamazons3uploadpartsizebytes - :displayname: Export Amazon S3 upload part size (File Storage) - :systemconsole: N/A - :configjson: .FileSettings.ExportAmazonS3UploadPartSizeBytes - :environment: MM_FILESETTINGS_EXPORTAMAZONS3UPLOADPARTSIZEBYTES - :description: The size, in bytes, of each part in a multi-part exported to Amazon S3. Default value is 104857600 (100MB). - -Amazon S3 exported upload part size -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -+---------------------------------------------------------------+--------------------------------------------------------------------------------------------+ -| The size, in bytes, of each part in a multi-part | - System Config path: N/A | -| exported to Amazon S3. | - ``config.json`` setting: ``".FileSettings.ExportAmazonS3UploadPartSizeBytes: 104857600`` | -| | - Environment variable: ``MM_FILESETTINGS_EXPORTAMAZONS3UPLOADPARTSIZEBYTES`` | -| Numeric value. Default is 104857600 (100MB). | | -+---------------------------------------------------------------+--------------------------------------------------------------------------------------------+ -| **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. | -+---------------------------------------------------------------+--------------------------------------------------------------------------------------------+ - -.. config:setting:: file-initialfont - :displayname: Initial font (File Storage) - :systemconsole: N/A - :configjson: .FileSettings.InitialFont - :environment: MM_FILESETTINGS_INITIALFONT - :description: The font used in auto-generated profile pictures with colored backgrounds and username initials. Default value is **nunito-bold.ttf**. - -Initial font -~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+--------------------------------------------------------------------------------+ -| The font used in auto-generated profile pictures with colored | - System Config path: N/A | -| backgrounds and username initials. | - ``config.json`` setting: ``".FileSettings.InitialFont: nunito-bold.ttf",`` | -| | - Environment variable: ``MM_FILESETTINGS_INITIALFONT`` | -| A string with the font file name. Default is | | -| **nunito-bold.ttf**. | | -+---------------------------------------------------------------+--------------------------------------------------------------------------------+ - -.. config:setting:: file-amazons3requesttimeoutmilliseconds - :displayname: Amazon S3 request timeout (File Storage) - :systemconsole: N/A - :configjson: .FileSettings.AmazonS3RequestTimeoutMilliseconds - :environment: MM_FILESETTINGS_AMAZONS3REQUESTTIMEOUTMILLISECONDS - :description: Amount of time, in milliseconds, before requests to Amazon S3 time out. Default value is 30000 (30 seconds). - -Amazon S3 request timeout -~~~~~~~~~~~~~~~~~~~~~~~~~ - -+---------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| The amount of time, in milliseconds, before requests to | - System Config path: N/A | -| Amazon S3 storage time out. | - ``config.json`` setting: ``".FileSettings.AmazonS3RequestTimeoutMilliseconds: 30000`` | -| | - Environment variable: ``MM_FILESETTINGS_AMAZONS3REQUESTTIMEOUTMILLISECONDS`` | -| Default is 30000 (30 seconds). | | -+---------------------------------------------------------------+-----------------------------------------------------------------------------------------+ - diff --git a/source/configure/high-availability-configuration-settings.rst b/source/configure/high-availability-configuration-settings.rst deleted file mode 100644 index 9d37db59660..00000000000 --- a/source/configure/high-availability-configuration-settings.rst +++ /dev/null @@ -1,282 +0,0 @@ -.. _high-availability: - -:orphan: -:nosearch: - -You can configure Mattermost as a :doc:`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. - -.. config:setting:: ha-enable - :displayname: Enable high availability mode (High Availability) - :systemconsole: Environment > High Availability - :configjson: .ClusterSettings.Enable - :environment: MM_CLUSTERSETTINGS_ENABLE - - - **true**: The Mattermost server will attempt inter-node communication with the other servers in the cluster that have the same cluster name. - - **false**: **(Default)** Mattermost high availability mode is disabled. - -Enable high availability mode -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E20

- -+-----------------------------------------------------------------+------------------------------------------------------------+ -| You can enable high availability mode. | - System Config path: **Environment > High Availability** | -| | - ``config.json`` setting: ``".ClusterSettings.Enable",`` | -| - **true**: The Mattermost server will attempt inter-node | - Environment variable: ``MM_CLUSTERSETTINGS_ENABLE`` | -| communication with the other servers in the cluster that | | -| have the same cluster name. This sets the System Console to | | -| read-only mode to keep the servers' ``config.json`` files | | -| in sync. | | -| - **false**: **(Default)** Mattermost high availability mode | | -| is disabled. | | -+-----------------------------------------------------------------+------------------------------------------------------------+ - -.. config:setting:: ha-clustername - :displayname: Cluster name (High Availability) - :systemconsole: Environment > High Availability - :configjson: .ClusterSettings.ClusterName - :environment: MM_CLUSTERSETTINGS_CLUSTERNAME - :description: The cluster to join by name in a high availability cluster-based deployment. - -Cluster name -~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E20

- -+------------------------------------------------------------------------------+-----------------------------------------------------------------+ -| The cluster to join by name in a high availability cluster-based deployment. | - System Config path: **Environment > High Availability** | -| | - ``config.json`` setting: ``".ClusterSettings.ClusterName",`` | -| Only nodes with the same cluster name will join together. | - Environment variable: ``MM_CLUSTERSETTINGS_CLUSTERNAME`` | -| This is to support blue-green deployments or staging pointing | | -| to the same database. | | -+------------------------------------------------------------------------------+-----------------------------------------------------------------+ - -.. config:setting:: ha-overridehostname - :displayname: Override hostname (High Availability) - :systemconsole: Environment > High Availability - :configjson: .ClusterSettings.OverrideHostname - :environment: MM_CLUSTERSETTINGS_OVERRIDEHOSTNAME - :description: Override the hostname of this server. - -Override hostname -~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E20

- -+-----------------------------------------------------------------+------------------------------------------------------------------------+ -| You can override the hostname of this server. | - System Config path: **Environment > High Availability** | -| | - ``config.json`` setting: ``".ClusterSettings.OverrideHostname",`` | -| - This property can be set to a specific IP address if needed; | - Environment variable: ``MM_CLUSTERSETTINGS_OVERRIDEHOSTNAME`` | -| however, we don’t recommend overriding the hostname unless | | -| it's necessary. | | -| - If left blank, Mattermost attempts to get the hostname from | | -| the operating system or uses the IP address. | | -+-----------------------------------------------------------------+------------------------------------------------------------------------+ -| See the :doc:`high availability cluster-based deployment ` documentation for details. | -+-----------------------------------------------------------------+------------------------------------------------------------------------+ - -.. config:setting:: ha-useipaddress - :displayname: Use IP address (High Availability) - :systemconsole: Environment > High Availability - :configjson: .ClusterSettings.UseIPAddress - :environment: MM_CLUSTERSETTINGS_USEIPADDRESS - - - **true**: **(Default)** The cluster attempts to communicate using the IP address specified. - - **false**: The cluster attempts to communicate using the hostname. - -Use IP address -~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E20

- -+------------------------------------------------------------------------------+------------------------------------------------------------------------+ -| You can configure your high availability cluster-based deployment to | - System Config path: **Environment > High Availability** | -| communicate using the hostname instead of the IP address. | - ``config.json`` setting: ``".ClusterSettings.UseIPAddress: true",`` | -| | - Environment variable: ``MM_CLUSTERSETTINGS_USEIPADDRESS`` | -| - **true**: **(Default)** The cluster attempts to communicate | | -| using the IP address specified. | | -| - **false**: The cluster attempts to communicate using the | | -| hostname. | | -+------------------------------------------------------------------------------+------------------------------------------------------------------------+ - -.. config:setting:: ha-usegossip - :displayname: Use gossip (High Availability) - :systemconsole: Environment > High Availability - :configjson: .ClusterSettings.UseExperimentalGossip - :environment: MM_CLUSTERSETTINGS_USEEXPERIMENTALGOSSIP - - - **true**: **(Default)** The server attempts to communicate via the gossip protocol over the gossip port specified. - - **false**: The server attempts to communicate over the streaming port. - -Enable experimental gossip encryption -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E20

- -+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ -| Gossip encryption uses AES-256 by default, and this value isn’t | - System Config path: **Environment > High Availability** | -| configurable by design. | - ``config.json`` setting: ``".ClusterSettings.EnableExperimentalGossipEncryption: false”,`` | -| | - Environment variable: ``MM_CLUSTERSETTINGS_ENABLEEXPERIMENTALGOSSIPENCRYPTION`` | -| - **true**: **(Default for Cloud deployments)** | | -| All communication through the cluster using the gossip | | -| protocol will be encrypted. | | -| - **false**: **(Default for self-hosted deployments)** | | -| All communication using gossip protocol remains unchanged. | | -| protocol remains unencrypted. | | -+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ -| **Note**: Alternatively, you can manually set the ``ClusterEncryptionKey`` row value in the **Systems** table. A key is a byte array converted to base64. | -| Set this value to either 16, 24, or 32 bytes to select AES-128, AES-192, or AES-256 respectively. | -+-----------------------------------------------------------------+----------------------------------------------------------------------------------------------+ - -.. config:setting:: ha-gossipcompression - :displayname: Enable gossip compression (High Availability) - :systemconsole: Environment > High Availability - :configjson: .ClusterSettings.EnableGossipCompression - :environment: MM_CLUSTERSETTINGS_ENABLEGOSSIPCOMPRESSION - - - **true**: **(Default)** All communication through the cluster uses gossip compression. - - **false**: All communication using the gossip protocol remains uncompressed. - -Enable gossip compression -~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E20

- -+-----------------------------------------------------------------+----------------------------------------------------------------------------------+ -| We recommend that you disable this configuration | - System Config path: **Environment > High Availability** | -| setting for better performance. | - ``config.json`` setting: ``".ClusterSettings.EnableGossipCompression: true”,`` | -| | - Environment variable: ``MM_CLUSTERSETTINGS_ENABLEGOSSIPCOMPRESSION`` | -| - **true**: **(Default for self-hosted deployments)** | | -| All communication through the cluster uses gossip | | -| compression. This setting is enabled by default to maintain | | -| compatibility with older servers. | | -| - **false**: **(Default for Cloud deployments)** | | -| All communication using the gossip protocol remains | | -| uncompressed. | | -| | | -+-----------------------------------------------------------------+----------------------------------------------------------------------------------+ - -.. config:setting:: ha-gossipport - :displayname: Gossip port (High Availability) - :systemconsole: Environment > High Availability - :configjson: .ClusterSettings.GossipPort - :environment: MM_CLUSTERSETTINGS_GOSSIPPORT - :description: The port used for the gossip protocol. Both UDP and TCP should be allowed on this port. Default value is **8074**. - -Gossip port -~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E20

- -+-----------------------------------------------------------------+---------------------------------------------------------------------+ -| The port used for the gossip protocol. Both UDP and TCP | - System Config path: **Environment > High Availability** | -| should be allowed on this port. | - ``config.json`` setting: ``".ClusterSettings.GossipPort: 8074”,`` | -| | - Environment variable: ``MM_CLUSTERSETTINGS_GOSSIPPORT`` | -| Numerical input. Default is **8074**. | | -+-----------------------------------------------------------------+---------------------------------------------------------------------+ - -.. config:setting:: ha-readonlyconfig - :displayname: Read only config (High Availability) - :systemconsole: N/A - :configjson: .ClusterSettings.ReadOnlyConfig - :environment: MM_CLUSTERSETTINGS_READONLYCONFIG - :description: Configure whether changes made in the System Console are written to config.json or ignored. Default is ignored. - -Read only config -~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E20

- -+-----------------------------------------------------------------+------------------------------------------------------------------------+ -| - **true**: **(Default)** Changes made to settings in the | - System Config path: N/A | -| System Console are ignored. | - ``config.json`` setting: ``".ClusterSettings.ReadOnlyConfig: true,`` | -| - **false**: Changes made to settings in the System Console | - Environment variable: ``MM_CLUSTERSETTINGS_READONLYCONFIG`` | -| are written to ``config.json``. | | -+-----------------------------------------------------------------+------------------------------------------------------------------------+ - -.. config:setting:: ha-networkinterface - :displayname: Network interface (High Availability) - :systemconsole: N/A - :configjson: .ClusterSettings.NetworkInterface - :environment: MM_CLUSTERSETTINGS_NETWORKINTERFACE - :description: An IP address used to identify the device that does automatic IP detection in high availability cluster-based deployments. - -Network interface -~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E20

- -+-----------------------------------------------------------------+------------------------------------------------------------------------+ -| An IP address used to identify the device that does automatic | - System Config path: N/A | -| IP detection in high availability cluster-based deployments. | - ``config.json`` setting: ``".ClusterSettings.NetworkInterface: "",`` | -| | - Environment variable: ``MM_CLUSTERSETTINGS_NETWORKINTERFACE`` | -| String input. | | -+-----------------------------------------------------------------+------------------------------------------------------------------------+ - -.. config:setting:: ha-bindaddress - :displayname: Bind address (High Availability) - :systemconsole: N/A - :configjson: .ClusterSettings.BindAddress - :environment: MM_CLUSTERSETTINGS_BINDADDRESS - :description: An IP address used to bind cluster traffic to a specific network device. - -Bind address -~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E20

- -+-----------------------------------------------------------------+--------------------------------------------------------------------+ -| An IP address used to bind cluster traffic to a specific | - System Config path: N/A | -| network device. | - ``config.json`` setting: ``".ClusterSettings.BindAddress: "",`` | -| | - Environment variable: ``MM_CLUSTERSETTINGS_BINDADDRESS`` | -| This setting is used primarily for servers with multiple | | -| network devices or different Bind Address and Advertise Address | | -| like in deployments that involve NAT (Network Address | | -| Translation). | | -| | | -| String input. | | -+-----------------------------------------------------------------+--------------------------------------------------------------------+ - -.. config:setting:: ha-advertiseaddress - :displayname: Advertise address (High Availability) - :systemconsole: N/A - :configjson: .ClusterSettings.AdvertiseAddress - :environment: MM_CLUSTERSETTINGS_ADVERTISEADDRESS - :description: The IP address used to access the server from other nodes. - -Advertise address -~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E20

- -+-----------------------------------------------------------------+------------------------------------------------------------------------+ -| The IP address used to access the server from other nodes. | - System Config path: N/A | -| This settings is used primary when cluster nodes are not in | - ``config.json`` setting: ``".ClusterSettings.AdvertiseAddress: "",`` | -| the same network and involve NAT (Network Address Translation). | - Environment variable: ``MM_CLUSTERSETTINGS_ADVERTISEADDRESS`` | -| | | -| String input. | | -+-----------------------------------------------------------------+------------------------------------------------------------------------+ \ No newline at end of file diff --git a/source/configure/image-proxy-configuration-settings.rst b/source/configure/image-proxy-configuration-settings.rst deleted file mode 100644 index 1e5ff626eb4..00000000000 --- a/source/configure/image-proxy-configuration-settings.rst +++ /dev/null @@ -1,100 +0,0 @@ -:orphan: -:nosearch: - -An image proxy is used by Mattermost apps to prevent them from connecting directly to remote self-hosted servers. Configure an image proxy by going to **System Console > Environment > Image Proxy**, or by editing the ``config.json`` file as described in the following tables. - -.. config:setting:: image-enableproxy - :displayname: Enable image proxy (Image Proxy) - :systemconsole: Environment > Image Proxy - :configjson: .ImageProxySettings.Enable - :environment: MM_IMAGEPROXYSETTINGS_ENABLE - - - **true**: **(Default)** Enables an image proxy for loading external images. - - **false**: Disables the image proxy. - -Enable image proxy -~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+---------------------------------------------------------------------+ -| An image proxy anonymizes Mattermost app connections and | - System Config path: **Environment > Image Proxy** | -| prevents them from accessing insecure content. | - ``config.json setting``: ``".ImageProxySettings.Enable": true",`` | -| | - Environment variable: ``MM_IMAGEPROXYSETTINGS_ENABLE`` | -| - **true**: **(Default)** Enables an image proxy for loading | | -| external images. | | -| - **false**: Disables the image proxy. | | -+---------------------------------------------------------------+---------------------------------------------------------------------+ -| See the :doc:`image proxy ` documentation to learn more. | -+---------------------------------------------------------------+---------------------------------------------------------------------+ - -.. config:setting:: image-proxytype - :displayname: Image proxy type (Image Proxy) - :systemconsole: Environment > Image Proxy - :configjson: .ImageProxySettings.ImageProxyType - :environment: MM_IMAGEPROXYSETTINGS_IMAGEPROXYTYPE - :description: The type of image proxy used by Mattermost. - - - **local**: **(Default)** The Mattermost server itself acts as the image proxy. - - **atmos/camo**: An external atmos/camo image proxy is used. - -Image proxy type -~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+-------------------------------------------------------------------------------+ -| The type of image proxy used by Mattermost. | - System Config path: **Environment > Image Proxy** | -| | - ``config.json setting``: ``".ImageProxySettings.ImageProxyType": "local",`` | -| - **local**: **(Default)** The Mattermost server itself acts | - Environment variable: ``MM_IMAGEPROXYSETTINGS_IMAGEPROXYTYPE`` | -| as the image proxy. | | -| - **atmos/camo**: An external atmos/camo image proxy is used. | | -+---------------------------------------------------------------+-------------------------------------------------------------------------------+ -| See the :doc:`image proxy ` documentation to learn more. | -+---------------------------------------------------------------+-------------------------------------------------------------------------------+ - -.. config:setting:: image-remoteimageproxyurl - :displayname: Remote image proxy URL (Image Proxy) - :systemconsole: Environment > Image Proxy - :configjson: .ImageProxySettings.RemoteImageProxyURL - :environment: MM_IMAGEPROXYSETTINGS_REMOTEIMAGEPROXYURL - :description: The URL of the atmos/camo proxy. - -Remote image proxy URL -~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+---------------------------------------------------------------------------+ -| The URL of the atmos/camo proxy. This setting isn't needed | - System Config path: **Environment > Image Proxy** | -| when using the **local** image proxy. | - ``config.json setting``: ``".ImageProxySettings.RemoteImageProxyURL",`` | -| | - Environment variable: ``MM_IMAGEPROXYSETTINGS_REMOTEIMAGEPROXYURL`` | -+---------------------------------------------------------------+---------------------------------------------------------------------------+ - -.. config:setting:: image-remoteimageproxyoptions - :displayname: Remote image proxy options (Image Proxy) - :systemconsole: Environment > Image Proxy - :configjson: .ImageProxySettings.RemoteImageProxyOptions - :environment: MM_IMAGEPROXYSETTINGS_REMOTEIMAGEPROXYOPTIONS - :description: The URL signing key passed to an atmos/camo image proxy. - -Remote image proxy options -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+-------------------------------------------------------------------------------+ -| The URL signing key passed to an atmos/camo image proxy. | - System Config path: **Environment > Image Proxy** | -| This setting isn't needed when using the **local** image | - ``config.json setting``: ``".ImageProxySettings.RemoteImageProxyOptions",`` | -| proxy type. | - Environment variable: ``MM_IMAGEPROXYSETTINGS_REMOTEIMAGEPROXYOPTIONS`` | -+---------------------------------------------------------------+-------------------------------------------------------------------------------+ -| See the :doc:`image proxy ` documentation to learn more. | -+---------------------------------------------------------------+-------------------------------------------------------------------------------+ diff --git a/source/configure/logging-configuration-settings.rst b/source/configure/logging-configuration-settings.rst deleted file mode 100644 index a19498b91e8..00000000000 --- a/source/configure/logging-configuration-settings.rst +++ /dev/null @@ -1,348 +0,0 @@ -:orphan: -:nosearch: - -Configure logging by going to **System Console > Environment > Logging**, or by editing the ``config.json`` file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect. - -.. tip:: - - You can manage additional logging configuration within the ``config.json`` file specifically for Mattermost notifications under ``NotificationLogSettings``. These settings are equivalent to the configuration settings available under ``LogSettings``. - -.. config:setting:: log-enableconsole - :displayname: Output logs to console (Logging) - :systemconsole: Environment > Logging - :configjson: .LogSettings.EnableConsole - :environment: MM_LOGSETTINGS_ENABLECONSOLE - - - **true**: **(Default)** Output log messages are written to the console based on the `console log level <#console-log-level>`__ configuration. - - **false**: Output log messages aren’t written to the console. - -Output logs to console -~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+-----------------------------------------------+---------------------------------------------------------------------+ -| Configure Mattermost to output logs to the | - System Config path: **Environment > Logging** | -| console. | - ``config.json setting``: ``".LogSettings.EnableConsole": true",`` | -| | - Environment variable: ``MM_LOGSETTINGS_ENABLECONSOLE`` | -| - **true**: **(Default)** Output log messages | | -| are written to the console based on the | | -| `console log level <#console-log-level>`__ | | -| configuration. The server writes messages | | -| to the standard output stream (stdout). | | -| - **false**: Output log messages aren’t | | -| written to the console. | | -+-----------------------------------------------+---------------------------------------------------------------------+ - -.. config:setting:: log-consolelevel - :displayname: Console log level (Logging) - :systemconsole: Environment > Logging - :configjson: .LogSettings.ConsoleLevel - :environment: MM_LOGSETTINGS_CONSOLELEVEL - :description: The level of detail in log events written when Mattermost outputs log messages to the console. - - - **DEBUG**: **(Default)** Outputs verbose detail for developers debugging issues. - - **ERROR**: Outputs only error messages. - - **INFO**: Outputs error messages and information around startup and initialization. - -Console log level -~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+-----------------------------------------------+---------------------------------------------------------------------+ -| The level of detail in log events written | - System Config path: **Environment > Logging** | -| when Mattermost outputs log messages to the | - ``config.json setting``: ``".LogSettings.ConsoleLevel": DEBUG",`` | -| console. | - Environment variable: ``MM_LOGSETTINGS_CONSOLELEVEL`` | -| | | -| - **DEBUG**: **(Default)** Outputs verbose | | -| detail for developers debugging issues. | | -| - **ERROR**: Outputs only error messages. | | -| - **INFO**: Outputs error messages and | | -| information around startup and | | -| initialization. | | -+-----------------------------------------------+---------------------------------------------------------------------+ - -.. config:setting:: log-consolejson - :displayname: Output console logs as JSON (Logging) - :systemconsole: Environment > Logging - :configjson: .LogSettings.ConsoleJson - :environment: MM_LOGSETTINGS_CONSOLEJSON - :description: Configure Mattermost to output console logs as JSON. - - - **true**: **(Default)** Logged events are written in a machine-readable JSON format. - - **false**: Logged events are written in plain text. - -Output console logs as JSON -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+-----------------------------------------------+---------------------------------------------------------------------+ -| Configure Mattermost to output console logs | - System Config path: **Environment > Logging** | -| as JSON. | - ``config.json setting``: ``".LogSettings.ConsoleJson": true",`` | -| | - Environment variable: ``MM_LOGSETTINGS_CONSOLEJSON`` | -| - **true**: **(Default)** Logged events are | | -| written in a machine-readable JSON format. | | -| - **false**: Logged events are written in | | -| plain text. | | -+-----------------------------------------------+---------------------------------------------------------------------+ -| **Note**: Typically set to **true** in a production environment. | -+-----------------------------------------------+---------------------------------------------------------------------+ - -.. config:setting:: log-enableplaintextcolor - :displayname: Colorize plain text console logs (Logging) - :systemconsole: N/A - :configjson: .LogSettings.EnableColor - :environment: MM_LOGSETTINGS_ENABLECOLOR - :description: Enables system admins to display plain text log level details in color. - - - **true**: When logged events are output to the console as plain text, colorize log levels details. - - **false**: **(Default)** Plain text log details aren't colorized in the console. - -Colorize plain text console logs -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -+-----------------------------------------------+----------------------------------------------------------------------+ -| Enables system admins to display plain text | - System Config path: N/A | -| log level details in color. | - ``config.json setting``: ``".LogSettings.EnableColor": false",`` | -| | - Environment variable: ``MM_LOGSETTINGS_ENABLECOLOR`` | -| - **true**: When logged events are output to | | -| the console as plain text, colorize log | | -| levels details. | | -| - **false**: **(Default)** Plain text log | | -| details aren't colorized in the console. | | -+-----------------------------------------------+----------------------------------------------------------------------+ - -.. config:setting:: log-enablefile - :displayname: Output logs to file (Logging) - :systemconsole: Environment > Logging - :configjson: .LogSettings.EnableFile - :environment: MM_LOGSETTINGS_ENABLEFILE - :description: Configure Mattermost to output console logs to a file. - - - **true**: **(Default)** Logged events are written based on the `file log level <#file-log-level>`__ configuration to a ``mattermost.log`` file located in the directory configured via file location. - - **false**: Logged events aren’t written to a file. - -Output logs to file -~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+-----------------------------------------------+---------------------------------------------------------------------+ -| Configure Mattermost to output console logs | - System Config path: **Environment > Logging** | -| to a file. | - ``config.json setting``: ``".LogSettings.EnableFile": true",`` | -| | - Environment variable: ``MM_LOGSETTINGS_ENABLEFILE`` | -| - **true**: **(Default)** Logged events are | | -| written based on the | | -| `file log level <#file-log-level>`__ | | -| configuration to a ``mattermost.log`` file | | -| located in the directory configured via | | -| ``file location``. | | -| - **false**: Logged events aren’t written to | | -| a file. | | -+-----------------------------------------------+---------------------------------------------------------------------+ -| **Note**: Typically set to **true** in a production environment. When enabled, you can download the | -| ``mattermost.log`` file locally by going to **System Console > Reporting > Server Logs**, and selecting **Download | -| Logs**. | -+-----------------------------------------------+---------------------------------------------------------------------+ - -.. config:setting:: log-filelocation - :displayname: File log directory (Logging) - :systemconsole: Environment > Logging - :configjson: .LogSettings.FileLocation - :environment: MM_LOGSETTINGS_FILELOCATION - :description: The location of the log files. Default value is **./logs**. - -File log directory -~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+-----------------------------------------------+---------------------------------------------------------------------+ -| The location of the log files. | - System Config path: **Environment > Logging** | -| | - ``config.json setting``: ``".LogSettings.FileLocation": "",`` | -| String input. If left blank, log files are | - Environment variable: ``MM_LOGSETTINGS_FILELOCATION`` | -| stored in the ``./logs`` directory. | | -+-----------------------------------------------+---------------------------------------------------------------------+ -| **Note**: The path you configure must exist, and Mattermost must have write permissions for this directory. | -+-----------------------------------------------+---------------------------------------------------------------------+ - -.. config:setting:: log-filelevel - :displayname: File log level (Logging) - :systemconsole: Environment > Logging - :configjson: .LogSettings.FileLevel - :environment: MM_LOGSETTINGS_FILELEVEL - :description: The level of detail in log events when Mattermost outputs log messages to a file. - - - **DEBUG**: Outputs verbose detail for developers debugging issues. - - **ERROR**: Outputs only error messages. - - **INFO**: **(Default)** Outputs error messages and information around startup and initialization. - -File log level -~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+-----------------------------------------------+---------------------------------------------------------------------+ -| The level of detail in log events when | - System Config path: **Environment > Logging** | -| Mattermost outputs log messages to a file. | - ``config.json setting``: ``".LogSettings.FileLevel": INFO",`` | -| | - Environment variable: ``MM_LOGSETTINGS_FILELEVEL`` | -| - **DEBUG**: Outputs verbose detail for | | -| developers debugging issues. | | -| - **ERROR**: Outputs only error messages. | | -| - **INFO**: **(Default)** Outputs error | | -| messages and information around startup | | -| and initialization. | | -+-----------------------------------------------+---------------------------------------------------------------------+ - -.. config:setting:: log-filejson - :displayname: Output file logs as JSON (Logging) - :systemconsole: Environment > Logging - :configjson: .LogSettings.FileJson - :environment: MM_LOGSETTINGS_FILEJSON - :description: Configure Mattermost to output file logs as JSON. - - - **true**: **(Default)** Logged events are written in a machine-readable JSON format. - - **false**: Logged events are written in plain text. - -Output file logs as JSON -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+-----------------------------------------------+---------------------------------------------------------------------+ -| Configure Mattermost to output file logs as | - System Config path: **Environment > Logging** | -| JSON. | - ``config.json setting``: ``".LogSettings.FileJson": true",`` | -| | - Environment variable: ``MM_LOGSETTINGS_FILEJSON`` | -| - **true**: **(Default)** Logged events are | | -| written in a machine-readable JSON format. | | -| - **false**: Logged events are written in | | -| plain text. | | -+-----------------------------------------------+---------------------------------------------------------------------+ -| **Note**: Typically set to **true** in a production environment. | -+-----------------------------------------------+---------------------------------------------------------------------+ - -.. config:setting:: log-enablewebhookdebug - :displayname: Enable webhook debugging (Logging) - :systemconsole: Environment > Logging - :configjson: .LogSettings.EnableWebhookDebugging - :environment: MM_LOGSETTINGS_ENABLEWEBHOOKDEBUGGING - :description: Configure Mattermost to capture the contents of incoming webhooks to log files for debugging. - - - **true**: **(Default)** The contents of incoming webhooks are printed to console and/or file logs for debugging. - - **false**: The contents of incoming webhooks aren’t printed to log files. - -Enable webhook debugging -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+-----------------------------------------------+------------------------------------------------------------------------------+ -| Configure Mattermost to capture the contents | - System Config path: **Environment > Logging** | -| of incoming webhooks to console and/or file | - ``config.json setting``: ``".LogSettings.EnableWebhookDebugging": true",`` | -| logs for debugging. | - Environment variable: ``MM_LOGSETTINGS_ENABLEWEBHOOKDEBUGGING`` | -| | | -| - **true**: **(Default)** The contents of | | -| incoming webhooks are printed to log files | | -| for debugging. | | -| - **false**: The contents of incoming | | -| webhooks aren’t printed to log files. | | -+-----------------------------------------------+------------------------------------------------------------------------------+ -| **Note**: Enable debug logs by changing the :ref:`file log level ` to ``DEBUG`` to include | -| the request body of incoming webhooks in logs. | -+-----------------------------------------------+------------------------------------------------------------------------------+ - -.. config:setting:: log-multipletargetoutput - :displayname: Output logs to multiple targets (Logging) - :systemconsole: Environment > Logging - :configjson: .LogSettings.AdvancedLoggingJSON - :environment: MM_LOGSETTINGS_ADVANCEDLOGGINGJSON - :description: Configure Mattermost to allow any combination of console, local file, syslog, and TCP socket targets, and send log records to multiple targets. - -Output logs to multiple targets -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+-----------------------------------------------+---------------------------------------------------------------------------+ -| Configure Mattermost to allow any combination | - System Config path: **Environment > Logging** | -| of console, local file, syslog, and TCP | - ``config.json setting``: ``".LogSettings.AdvancedLoggingJSON":: "",`` | -| socket targets, and send log records to | - Environment variable: ``MM_LOGSETTINGS_ADVANCEDLOGGINGJSON`` | -| multiple targets. | | -| | | -| String input can contain a filespec to | | -| another configuration file, a database DSN, | | -| or JSON. | | -+-----------------------------------------------+---------------------------------------------------------------------------+ -| **Notes**: | -| | -| - These targets have been chosen as they support the vast majority of log aggregators, and other log analysis tools, | -| without needing additional software installed. | -| - Logs are recorded asynchronously to reduce latency to the caller. | -| - Advanced logging supports hot-reloading of logger configuration. | -+-----------------------------------------------+---------------------------------------------------------------------------+ -| **Note**: See the :doc:`Mattermost logging ` documentation for details. | -+-----------------------------------------------+---------------------------------------------------------------------------+ - -.. config:setting:: log-maxfieldsize - :displayname: Maximum field size (Logging) - :systemconsole: N/A - :configjson: .LogSettings.MaxFieldSize - :environment: MM_LOGSETTINGS_MAXFIELDSIZE - :description: Enables system admins to limit the size of log fields during logging. Default is **2048**. - -Maximum field size -~~~~~~~~~~~~~~~~~~ - -+-----------------------------------------------+----------------------------------------------------------------------+ -| Enables system admins to limit the size of | - System Config path: N/A | -| log fields during logging. | - ``config.json setting``: ``".LogSettings.MaxFieldSize": 2048",`` | -| | - Environment variable: ``MM_LOGSETTINGS_MAXFIELDSIZE`` | -| Numerical value. Default is **2048**. | | -+-----------------------------------------------+----------------------------------------------------------------------+ - -.. config:setting:: log-enablediagnostics - :displayname: Enable diagnostics and error reporting (Logging) - :systemconsole: Environment > Logging - :configjson: .LogSettings.EnableDiagnostics - :environment: MM_LOGSETTINGS_ENABLEDIAGNOSTICS - :description: Send diagnostics and error reports to Mattermost, Inc. - -Enable diagnostics and error reporting -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+----------------------------------------------+-------------------------------------------------------------------------+ -| Whether or not diagnostics and error reports | - System Config path: **Environment > Logging** | -| are sent to Mattermost, Inc. | - ``config.json setting``: ``".LogSettings.EnableDiagnostics": "",`` | -| | - Environment variable: ``MM_LOGSETTINGS_ENABLEDIAGNOSTICS`` | -| - **true**: **(Default)** Send diagnostics | | -| and error reports. | | -| - **false**: Diagnostics and error reports | | -| aren't sent. | | -+----------------------------------------------+-------------------------------------------------------------------------+ -| **Note**: See the :ref:`telemetry ` docummentation for | -| details on the information Mattermost collects. | -+----------------------------------------------+-------------------------------------------------------------------------+ \ No newline at end of file diff --git a/source/configure/optimize-your-workspace.rst b/source/configure/optimize-your-workspace.rst index 414fde58eb8..c1ea6c95d3c 100644 --- a/source/configure/optimize-your-workspace.rst +++ b/source/configure/optimize-your-workspace.rst @@ -43,7 +43,7 @@ The following optimization areas can alert you to workspace suggestions, warning | | :start-after: :nosearch: | | +-----------------------+----------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Workspace access | Is the Mattermost workspace may not be accessible to users? | If your web server settings don't pass a live URL test, your workspace may not be accessible to others. | -| | | See the :doc:`Environment Configuration Settings ` product documentation to learn more: | +| | | See the :ref:`Web server configuration settings ` product documentation to learn more: | +-----------------------+----------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Search performance | As your user base grows, is search getting slower? | See the :doc:`Elasticsearch ` product documentation to learn more. | +-----------------------+----------------------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ diff --git a/source/configure/performance-monitoring-configuration-settings.rst b/source/configure/performance-monitoring-configuration-settings.rst deleted file mode 100644 index 0dad390f4ec..00000000000 --- a/source/configure/performance-monitoring-configuration-settings.rst +++ /dev/null @@ -1,57 +0,0 @@ -:orphan: -:nosearch: - -Configure performance monitoring by going to **System Console > Environment > Performance Monitoring**, or by editing the ``config.json`` file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect. - -.. config:setting:: perf-enablemonitoring - :displayname: Enable performance monitoring (Performance Monitoring) - :systemconsole: Environment > Performance Monitoring - :configjson: .MetricsSettings.Enable - :environment: MM_METRICSSETTINGS_ENABLE - :description: Enable or disable performance monitoring. - - - **true**: Performance monitoring data collection and profiling is enabled. - - **false**: **(Default)** Mattermost performance monitoring is disabled. - -Enable performance monitoring -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E20

- -+-----------------------------------------------+---------------------------------------------------------------------+ -| Enable or disable performance monitoring. | - System Config path: **Environment > Performance Monitoring** | -| | - ``config.json setting``: ``".MetricsSettings.Enable": false",`` | -| - **true**: Performance monitoring data | - Environment variable: ``MM_METRICSSETTINGS_ENABLE`` | -| collection and profiling is enabled. | | -| - **false**: **(Default)** Mattermost | | -| performance monitoring is disabled. | | -+-----------------------------------------------+---------------------------------------------------------------------+ -| See the :doc:`performance monitoring ` documentation | -| to learn more. | -+-----------------------------------------------+---------------------------------------------------------------------+ - -.. config:setting:: perf-listenaddress - :displayname: Listen address for performance (Performance Monitoring) - :systemconsole: Environment > Performance Monitoring - :configjson: .MetricsSettings.ListenAddress - :environment: MM_METRICSSETTINGS_LISTENADDRESS - :description: The port the Mattermost server will listen on to expose performance metrics, when enabled. Default is port **8067**. - -Listen address for performance -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E20

- -+---------------------------------------------------------------+-------------------------------------------------------------------------+ -| The port the Mattermost server will listen on to expose | - System Config path: **Environment > Performance Monitoring** | -| performance metrics, when enabled. | - ``config.json setting``: ``".MetricsSettings.ListenAddress": 8067",`` | -| | - Environment variable: ``MM_METRICSSETTINGS_LISTENADDRESS`` | -| Numerical input. Default is **8067**. | | -+---------------------------------------------------------------+-------------------------------------------------------------------------+ - - - diff --git a/source/configure/plugins-configuration-settings.rst b/source/configure/plugins-configuration-settings.rst index c763fa0cee2..28c252f4073 100644 --- a/source/configure/plugins-configuration-settings.rst +++ b/source/configure/plugins-configuration-settings.rst @@ -1080,7 +1080,7 @@ See the :doc:`Legal holds ` product documentation for detail :description: Connect your Microsoft Calendar to your Mattermost instance. Microsoft Calendar ----- +------------------- .. include:: ../_static/badges/allplans-cloud-selfhosted.rst :start-after: :nosearch: @@ -1098,7 +1098,7 @@ See the :doc:`Connect Microsoft Calendar to Mattermost 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. - -.. config:setting:: sessionlength-extendwithactivity - :displayname: Extend session length with activity (Session Lengths) - :systemconsole: Environment > Session Lengths - :configjson: .ServiceSettings.ExtendSessionLengthWithActivity - :environment: MM_SERVICESETTINGS_EXTENDSESSONLENGTHWITHACTIVITY - - - **true**: **(Default)** Sessions are automatically extended when users are active in their Mattermost client. - - **false**: Sessions won't extend with activity in Mattermost. - -Extend session length with activity -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+----------------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| Improves the user experience by extending sessions and keeping | - System Config path: **Environment > Session Lengths** | -| users logged in if they are active in their Mattermost apps. | - ``config.json`` setting: ``".ServiceSettings.ExtendSessionLengthWithActivity: true,`` | -| | - Environment variable: ``MM_SERVICESETTINGS_EXTENDSESSONLENGTHWITHACTIVITY`` | -| - **true**: **(Default)** Sessions are automatically | | -| extended when users are active in their Mattermost | | -| client. User sessions only expire when users aren’t active | | -| in their Mattermost client for the entire duration of the | | -| session lengths defined. | | -| - **false**: Sessions won't extend with activity in | | -| Mattermost. User sessions immediately expire at the | | -| end of the session length or based on the | | -| `session idle timeout <#session-idle-timeout>`__ configured. | | -+----------------------------------------------------------------+-----------------------------------------------------------------------------------------+ - -.. config:setting:: sessionlength-TerminateSessionsOnPasswordChange - :displayname: Terminate sessions on password change (Session Lengths) - :systemconsole: Environment > Session Lengths - :configjson: .ServiceSettings.TerminateSessionsOnPasswordChange - :environment: MM_SERVICESETTINGS_TERMINATESESSIONSONPASSWORDCHANGE - - - **true**: **(Default for new deployments)** Session revocation is enabled. All sessions of a user expire if their password is changed (by themselves or a system admin). If the password change is initiated by the user, their current session isn't terminated. - - **false**: **(Default for existing deployments)** Session revocation is disabled. When users change their password, only the user's current session is revoked. When a system admin changes the user's password, none of the user's sessions are revoked. - -Terminate sessions on password change -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -+----------------------------------------------------------------+-------------------------------------------------------------------------------------------+ -| Enable or disable session revocation when a user's | - System Config path: **Environment > Session Lengths** | -| password changes. | - ``config.json`` setting: ``".ServiceSettings.TerminateSessionsOnPasswordChange: true,`` | -| | - Environment variable: ``MM_SERVICESETTINGS_TERMINATESESSIONSONPASSWORDCHANGE`` | -| - **true**: **(Default for new deployments)** | | -| Session revocation is enabled. | | -| All sessions of a user expire if their password is changed | | -| (by themselves or by a system admin). If the password change | | -| is initiated by the user, their current session isn't | | -| terminated. | | -| - **false**: **(Default for existing deployments)** | | -| Session revocation is disabled. | | -| When users change their password, only the user's current | | -| session is revoked. When a system admin changes the user's | | -| password, none of the user's sessions are revoked. | | -+----------------------------------------------------------------+-------------------------------------------------------------------------------------------+ - -.. config:setting:: sessionlength-webinhours - :displayname: Session length for AD/LDAP and email (Session Lengths) - :systemconsole: Environment > Session Lengths - :configjson: .ServiceSettings.SessionLengthWebInHours - :environment: MM_SERVICESETTINGS_SESSONLENGTHWEBINHOURS - - Set the number of hours counted from the last time a user entered their credentials into the web app or the desktop app to the expiry of the user’s session on email and AD/LDAP authentication. - Default is **720** hours. - -Session length for AD/LDAP and email -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+----------------------------------------------------------------+--------------------------------------------------------------------------------+ -| Set the number of hours counted from the last time a user | - System Config path: **Environment > Session Lengths** | -| entered their credentials into the web app or the desktop | - ``config.json`` setting: ``".ServiceSettings.SessionLengthWebInHours: 720,`` | -| app to the expiry of the user’s session on email and AD/LDAP | - Environment variable: ``MM_SERVICESETTINGS_SESSONLENGTHWEBINHOURS`` | -| authentication. | | -| | | -| Numerical input in hours. Default is **720** hours. | | -+----------------------------------------------------------------+--------------------------------------------------------------------------------+ -| **Note**: After changing this setting, the new session length takes effect after the next time the user enters their credentials. | -+----------------------------------------------------------------+--------------------------------------------------------------------------------+ - -.. config:setting:: sessionlength-mobileinhours - :displayname: Session length for mobile (Session Lengths) - :systemconsole: Environment > Session Lengths - :configjson: .ServiceSettings.SessionLengthMobileInHours - :environment: MM_SERVICESETTINGS_SESSONLENGTHMOBILEINHOURS - :description: Set the number of hours counted from the last time a user entered their credential into the mobile app to the expiry of the user’s session. Default is **720** hours. - -Session length for mobile -~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+----------------------------------------------------------------+-----------------------------------------------------------------------------------+ -| Set the number of hours counted from the last time a user | - System Config path: **Environment > Session Lengths** | -| entered their credential into the mobile app to the expiry | - ``config.json`` setting: ``".ServiceSettings.SessionLengthMobileInHours: 720,`` | -| of the user’s session. | - Environment variable: ``MM_SERVICESETTINGS_SESSONLENGTHMOBILEINHOURS`` | -| | | -| Numerical input in hours. Default is **720** hours. | | -+----------------------------------------------------------------+-----------------------------------------------------------------------------------+ -| **Note**: After changing this setting, the new session length takes effect after the next time the user enters their credentials. | -+----------------------------------------------------------------+-----------------------------------------------------------------------------------+ - -.. config:setting:: sessionlength-ssoinhours - :displayname: Session length for SSO (Session Lengths) - :systemconsole: Environment > Session Lengths - :configjson: .ServiceSettings.SessionLengthSSOInHours - :environment: MM_SERVICESETTINGS_SESSONLENGTHSSOINHOURS - :description: Set the number of hours from the last time a user entered their SSO credentials to the expiry of the user’s session. Default is **720** hours. - -Session length for SSO -~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+----------------------------------------------------------------+----------------------------------------------------------------------------------+ -| Set the number of hours from the last time a user entered | - System Config path: **Environment > Session Lengths** | -| their SSO credentials to the expiry of the user’s session. | - ``config.json`` setting: ``".ServiceSettings.SessionLengthSSOInHours: 720,`` | -| This setting defines the session length for SSO | - Environment variable: ``MM_SERVICESETTINGS_SESSONLENGTHSSOINHOURS`` | -| authentication, such as SAML, GitLab, and OAuth 2.0. | | -| | | -| Numerical input in hours. Default is **720** hours. | | -| Numbers as decimals are also valid values for this | | -| configuration setting. | | -+----------------------------------------------------------------+----------------------------------------------------------------------------------+ -| **Notes**: | -| | -| - After changing this setting, the new session length takes effect after the next time the user enters their credentials. | -| - If the authentication method is SAML, GitLab, or OAuth 2.0, users may automatically be logged back in to Mattermost if they are already logged | -| in to SAML, GitLab, or with OAuth 2.0. | -+----------------------------------------------------------------+----------------------------------------------------------------------------------+ - -.. config:setting:: sessionlength-sessioncache - :displayname: Session cache (Session Lengths) - :systemconsole: Environment > Session Lengths - :configjson: .ServiceSettings.SessionCacheInMinutes - :environment: MM_SERVICESETTINGS_SESSONCACHEINMINUTES - :description: Set the number of minutes to cache a session in memory. Default is **10** minutes. - -Session cache -~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+----------------------------------------------------------------+-----------------------------------------------------------------------------+ -| Set the number of minutes to cache a session in memory. | - System Config path: **Environment > Session Lengths** | -| | - ``config.json`` setting: ``".ServiceSettings.SessionCacheInMinutes: 10,`` | -| Numerical input in minutes. Default is **10** minutes. | - Environment variable: ``MM_SERVICESETTINGS_SESSONCACHEINMINUTES`` | -+----------------------------------------------------------------+-----------------------------------------------------------------------------+ - -.. config:setting:: sessionlength-sessionidletimeout - :displayname: Session idle timeout (Session Lengths) - :systemconsole: N/A - :configjson: .ServiceSettings.SessionIdleTimeoutInMinutes - :environment: MM_SERVICESETTINGS_SESSONIDLETIMEOUTINMINUTES - - The number of minutes from the last time a user was active on the system to the expiry of the user’s session. Once expired, the user will need to log in to continue. - Default is **43200** minutes (30 days). Minimum value is 5 minutes, and a value of 0 sets the time as unlimited. - -Session idle timeout -~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+----------------------------------------------------------------+--------------------------------------------------------------------------------------+ -| The number of minutes from the last time a user was active | - System Config path: N/A | -| on the system to the expiry of the user’s session. | - ``config.json`` setting: ``".ServiceSettings.SessionIdleTimeoutInMinutes: 43200,`` | -| Once expired, the user will need to log in to continue. | - Environment variable: ``MM_SERVICESETTINGS_SESSONIDLETIMEOUTINMINUTES`` | -| | | -| Numerical input in minutes. Default is **43200** (30 days). | | -| Minimum value is **5** minutes, and a value of **0** sets | | -| the time as unlimited. | | -+----------------------------------------------------------------+--------------------------------------------------------------------------------------+ -| **Notes**: | -| | -| - This setting has no effect when `extend session length with activity <#extend-session-length-with-activity>`__ is set to **true**. | -| - This setting applies to the webapp and the desktop app. For mobile apps, use an | -| :doc:`EMM provider ` to lock the app when not in use. | -| - In :doc:`high availability mode `, enable IP hash load balancing for reliable | -| timeout measurement. | -+----------------------------------------------------------------+--------------------------------------------------------------------------------------+ diff --git a/source/configure/smtp-configuration-settings.rst b/source/configure/smtp-configuration-settings.rst deleted file mode 100644 index e3978221095..00000000000 --- a/source/configure/smtp-configuration-settings.rst +++ /dev/null @@ -1,211 +0,0 @@ -:orphan: -:nosearch: - -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. - -.. config:setting:: smtp-server - :displayname: SMTP server (SMTP) - :systemconsole: Environment > SMTP - :configjson: .EmailSettings.SMTPServer - :environment: MM_EMAILSETTINGS_SMTPSERVER - :description: The location of the SMTP email server used for email notifications. - -SMTP server -~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+-----------------------------------------------------------------+---------------------------------------------------------------+ -| The location of the SMTP email server used for email | - System Config path: **Environment > SMTP** | -| notifications. | - ``config.json setting``: ``".EmailSettings.SMTPServer",`` | -| | - Environment variable: ``MM_EMAILSETTINGS_SMTPSERVER`` | -+-----------------------------------------------------------------+---------------------------------------------------------------+ - -.. config:setting:: smtp-port - :displayname: SMTP server port (SMTP) - :systemconsole: Environment > SMTP - :configjson: .EmailSettings.SMTPPort - :environment: MM_EMAILSETTINGS_SMTPPORT - :description: The port of SMTP email server. - -SMTP server port -~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+-----------------------------------------------------------------+---------------------------------------------------------------+ -| The port of SMTP email server. | - System Config path: **Environment > SMTP** | -| | - ``config.json setting``: ``".EmailSettings.SMTPPort",`` | -| Numerical input. | - Environment variable: ``MM_EMAILSETTINGS_SMTPPORT`` | -+-----------------------------------------------------------------+---------------------------------------------------------------+ - -.. config:setting:: smtp-enableauth - :displayname: Enable SMTP authentication (SMTP) - :systemconsole: Environment > SMTP - :configjson: .EmailSettings.EnableSMTPAuth - :environment: MM_EMAILSETTINGS_ENABLESMTPAUTH - - - **true**: SMTP username and password are used for authenticating to the SMTP server. - - **false**: **(Default)** Mattermost doesn’t attempt to authenticate to the SMTP server. - -Enable SMTP authentication -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+-----------------------------------------------------------------+---------------------------------------------------------------------------+ -| Enable or disable SMTP authentication. | - System Config path: **Environment > SMTP** | -| | - ``config.json setting``: ``".EmailSettings.EnableSMTPAuth": false",`` | -| - **true**: SMTP username and password are used for | - Environment variable: ``MM_EMAILSETTINGS_ENABLESMTPAUTH`` | -| authenticating to the SMTP server. | | -| - **false**: **(Default)** Mattermost doesn’t attempt to | | -| authenticate to the SMTP server. | | -+-----------------------------------------------------------------+---------------------------------------------------------------------------+ - -.. config:setting:: smtp-username - :displayname: SMTP server username (SMTP) - :systemconsole: Environment > SMTP - :configjson: .EmailSettings.SMTPUsername - :environment: MM_EMAILSETTINGS_SMTPUSERNAME - :description: The username for authenticating to the SMTP server. - -SMTP server username -~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+-----------------------------------------------------------------+---------------------------------------------------------------+ -| The username for authenticating to the SMTP server. | - System Config path: **Environment > SMTP** | -| | - ``config.json setting``: ``".EmailSettings.SMTPUsername",`` | -| String input. | - Environment variable: ``MM_EMAILSETTINGS_SMTPUSERNAME`` | -+-----------------------------------------------------------------+---------------------------------------------------------------+ - -.. config:setting:: smtp-password - :displayname: SMTP server password (SMTP) - :systemconsole: Environment > SMTP - :configjson: .EmailSettings.SMTPPassword - :environment: MM_EMAILSETTINGS_SMTPPASSWORD - :description: The password associated with the SMTP username. - -SMTP server password -~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+-----------------------------------------------------------------+---------------------------------------------------------------+ -| The password associated with the SMTP username. | - System Config path: **Environment > SMTP** | -| | - ``config.json setting``: ``".EmailSettings.SMTPPassword",`` | -| String input. | - Environment variable: ``MM_EMAILSETTINGS_SMTPPASSWORD`` | -+-----------------------------------------------------------------+---------------------------------------------------------------+ - -.. config:setting:: smtp-connectionsecurity - :displayname: SMTP connection security (SMTP) - :systemconsole: Environment > SMTP - :configjson: .EmailSettings.ConnectionSecurity - :environment: MM_EMAILSETTINGS_CONNECTIONSECURITY - - - **Not specified**: **(Default)** Send email over an unsecure connection. - - **TLS**: Communication between Mattermost and your email server is encrypted. - - **STARTTLS**: Attempts to upgrade an existing insecure connection to a secure connection using TLS. - -SMTP connection security -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+-----------------------------------------------------------------+-----------------------------------------------------------------------+ -| Specify connection security for emails sent using SMTP. | - System Config path: **Environment > SMTP** | -| | - ``config.json setting``: ``".EmailSettings.ConnectionSecurity",`` | -| - **Not specified**: **(Default)** Send email over an | - Environment variable: ``MM_EMAILSETTINGS_CONNECTIONSECURITY`` | -| unsecure connection. | | -| - **TLS**: Communication between Mattermost and your email | | -| server is encrypted. | | -| - **STARTTLS**: Attempts to upgrade an existing insecure | | -| connection to a secure connection using TLS. | | -+-----------------------------------------------------------------+-----------------------------------------------------------------------+ - -.. config:setting:: smtp-skipservercertverification - :displayname: Skip server certificate verification (SMTP) - :systemconsole: Environment > SMTP - :configjson: .EmailSettings.SkipServerCertificateVerification - :environment: MM_EMAILSETTINGS_SKIPSERVERCERTIFICATEVERIFICATION - - - **true**: Mattermost won't verify the email server certificate. - - **false**: **(Default)** Mattermost verifies the email server certificate. - -Skip server certificate verification -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+-----------------------------------------------------------------------+----------------------------------------------------------------------------------------------+ -| Configure Mattermost to skip the verification of the email server | - System Config path: **Environment > SMTP** | -| certificate. | - ``config.json setting``: ``".EmailSettings.SkipServerCertificateVerification": false",`` | -| | - Environment variable: ``MM_EMAILSETTINGS_SKIPSERVERCERTIFICATEVERIFICATION`` | -| - **true**: Mattermost won't verify the email server certificate. | | -| - **false**: **(Default)** Mattermost verifies the email | | -| server certificate. | | -+-----------------------------------------------------------------------+----------------------------------------------------------------------------------------------+ - -.. config:setting:: smtp-enablesecurityalerts - :displayname: Enable security alerts (SMTP) - :systemconsole: Environment > SMTP - :configjson: .ServiceSettings.EnableSecurityFixAlert - :environment: MM_SERVICESETTINGS_ENABLESECURITYFIXALERT - - - **true**: **(Default)** System admins are notified by email if a relevant security fix alert is announced. Requires email to be enabled. - - **false**: Security alerts are disabled. - -Enable security alerts -~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+-----------------------------------------------------------------+------------------------------------------------------------------------------------+ -| Enable or disable security alerts. | - System Config path: **Environment > SMTP** | -| | - ``config.json setting``: ``".ServiceSettings.EnableSecurityFixAlert": true",`` | -| - **true**: **(Default)** System admins are notified by email | - Environment variable: ``MM_SERVICESETTINGS_ENABLESECURITYFIXALERT`` | -| if a relevant security fix alert is announced. Requires email | | -| to be enabled. | | -| - **false**: Security alerts are disabled. | | -+-----------------------------------------------------------------+------------------------------------------------------------------------------------+ -| See the :ref:`Telemetry ` documentation to learn more. | -+-----------------------------------------------------------------+------------------------------------------------------------------------------------+ - -.. config:setting:: smtp-servertimeout - :displayname: SMTP server timeout (SMTP) - :systemconsole: Environment > SMTP - :configjson: .EmailSettings.SMTPServerTimeout - :environment: MM_EMAILSETTINGS_SMTPSERVERTIMEOUT - :description: The maximum amount of time, in seconds, allowed for establishing a TCP connection between Mattermost and the SMTP server. - -SMTP server timeout -~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+-----------------------------------------------------------------+----------------------------------------------------------------------+ -| The maximum amount of time, in seconds, allowed for | - System Config path: **Environment > SMTP** | -| establishing a TCP connection between Mattermost and the SMTP | - ``config.json setting``: ``".EmailSettings.SMTPServerTimeout",`` | -| server. | - Environment variable: ``MM_EMAILSETTINGS_SMTPSERVERTIMEOUT`` | -| | | -| Numerical value in seconds. | | -+-----------------------------------------------------------------+----------------------------------------------------------------------+ diff --git a/source/configure/smtp-email.rst b/source/configure/smtp-email.rst index 6cbfbc4d0dd..ecab99a78d3 100644 --- a/source/configure/smtp-email.rst +++ b/source/configure/smtp-email.rst @@ -1,5 +1,3 @@ -.. _smtp-email-setup: - SMTP email setup ================ diff --git a/source/configure/web-server-configuration-settings.rst b/source/configure/web-server-configuration-settings.rst deleted file mode 100644 index c86e5dce60c..00000000000 --- a/source/configure/web-server-configuration-settings.rst +++ /dev/null @@ -1,726 +0,0 @@ -:orphan: -:nosearch: - -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. - -.. config:setting:: web-siteurl - :displayname: Site URL (Web Server) - :systemconsole: Environment > Web Server - :configjson: .ServiceSettings.SiteURL - :environment: MM_SERVICESETTINGS_SITEURL - :description: The URL that users use to access Mattermost. The port number is required if it’s not a standard port, such as 80 or 443. - -Site URL -~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+---------------------------------------------------------------+ -| The URL that users use to access Mattermost. | - System Config path: **Environment > Web Server** | -| The port number is required if it’s not a standard port, | - ``config.json`` setting: ``.ServiceSettings.SiteURL",`` | -| such as 80 or 443. This field is required. | - Environment variable: ``MM_SERVICESETTINGS_SITEURL`` | -| | | -| Select the **Test Live URL** button in the System Console | | -| to validate the Site URL. | | -+---------------------------------------------------------------+---------------------------------------------------------------+ -| **Notes**: | -| | -| - The URL may contain a subpath, such as ``https://example.com/company/mattermost``. | -| - If you change the Site URL value, log out of the Desktop App, and sign back in using the new domain. | -| - If Site URL is not set: | -| | -| - Email notifications will contain broken links, and email batching will not work. | -| - Authentication via OAuth 2.0, including GitLab, Google, and Entra ID, will fail. | -| - Plugins may not work as expected. | -+-------------------------------------------------------------------------------------------------------------------------------+ - -.. config:setting:: max-url-length - :displayname: Maximum URL length (Web Server) - :systemconsole: N/A - :configjson: .ServiceSettings.MaximumURLLength - :environment: MM_SERVICESETTINGS_MAXIMUMURLLENGTH - :description: The longest URL, in characters, including query parameters, accepted by the Mattermost server. Default is 2048 characters. - -Maximum URL length -~~~~~~~~~~~~~~~~~~ - -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| The longest URL, in characters, including query parameters, | - System Config path: N/A | -| accepted by the Mattermost server. Longer URLs are rejected, | - ``config.json`` setting: ``.ServiceSettings.MaximumURLLength: 2048",`` | -| and API calls fail with an error. | - Environment variable: ``MM_SERVICESETTINGS_MAXIMUMURLLENGTH`` | -| | | -| Numeric value. Default is **2048** characters. | | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ - -.. config:setting:: web-listenaddress - :displayname: Web server listen address (Web Server) - :systemconsole: Environment > Web Server - :configjson: .ServiceSettings.ListenAddress - :environment: MM_SERVICESETTINGS_LISTENADDRESS - - The address and port to which to bind and listen. Specifying ``:8065`` will bind to all network interfaces. - Specifying ``127.0.0.1:8065`` will only bind to the network interface having that IP address. - -Web server listen address -~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+------------------------------------------------------------------+ -| The address and port to which to bind and listen. | - System Config path: **Environment > Web Server** | -| Specifying ``:8065`` will bind to all network interfaces. | - ``config.json`` setting: ``".ServiceSettings.ListenAddress",`` | -| Specifying ``127.0.0.1:8065`` will only bind to the network | - Environment variable: ``MM_SERVICESETTINGS_LISTENADDRESS`` | -| interface having that IP address. | | -| | | -| If you choose a port of a lower level (called “system ports” | | -| or “well-known ports”, in the range of 0-1023), you must have | | -| permissions to bind to that port. | | -+---------------------------------------------------------------+------------------------------------------------------------------+ - -.. config:setting:: web-forwardinsecure - :displayname: Forward port 80 to 443 (Web Server) - :systemconsole: Environment > Web Server - :configjson: .ServiceSettings.Forward80To443 - :environment: MM_SERVICESETTINGS_FORWARD80TO443 - - - **true**: Forwards all insecure traffic from port 80 to secure port 443. - - **false**: **(Default)** When using a proxy such as NGINX in front of Mattermost this setting is unnecessary and should be set to false. - -Forward port 80 to 443 -~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+--------------------------------------------------------------------------+ -| Forward insecure traffic from port 80 to port 443. | - System Config path: **Environment > Web Server** | -| | - ``config.json`` setting: ``".ServiceSettings.Forward80To443: false",`` | -| - **true**: Forwards all insecure traffic from port 80 to | - Environment variable: ``MM_SERVICESETTINGS_FORWARD80TO443`` | -| secure port 443. | | -| - **false**: **(Default)** When using a proxy such as NGINX | | -| in front of Mattermost this setting is unnecessary | | -| and should be set to false. | | -+---------------------------------------------------------------+--------------------------------------------------------------------------+ - -.. config:setting:: web-connectionsecurity - :displayname: Web server connection security (Web Server) - :systemconsole: Environment > Web Server - :configjson: .ServiceSettings.ConnectionSecurity - :environment: MM_SERVICESETTINGS_CONNECTIONSECURITY - :description: Connection security between Mattermost clients and the server. - - - **Not specified**: Mattermost will connect over an unsecure connection. - - **TLS**: Encrypts the communication between Mattermost clients and your server. - -Web server connection security -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+-----------------------------------------------------------------------+-----------------------------------------------------------------------+ -| Connection security between Mattermost clients and the server. | - System Config path: **Environment > Web Server** | -| | - ``config.json`` setting: ``".ServiceSettings.ConnectionSecurity",`` | -| - **Not specified**: Mattermost will connect over an unsecure | - Environment variable: ``MM_SERVICESETTINGS_CONNECTIONSECURITY`` | -| connection. | | -| - **TLS**: Encrypts the communication between Mattermost | | -| clients and your server. See the :doc:`configuring TLS on | | -| Mattermost ` for more details. | | -+-----------------------------------------------------------------------+-----------------------------------------------------------------------+ - -.. config:setting:: web-tlscertificatefile - :displayname: TLS certificate file (Web Server) - :systemconsole: Environment > Web Server - :configjson: .ServiceSettings.TLSCertFile - :environment: MM_SERVICESETTINGS_TLSCERTFILE - :description: The path to the certificate file to use for TLS connection security. - -TLS certificate file -~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+--------------------------------------------------------+------------------------------------------------------------------+ -| The path to the certificate file to use for TLS | - System Config path: **Environment > Web Server** | -| connection security. | - ``config.json`` setting: ``".ServiceSettings.TLSCertFile",`` | -| | - Environment variable: ``MM_SERVICESETTINGS_TLSCERTFILE`` | -| String input. | | -+--------------------------------------------------------+------------------------------------------------------------------+ - -.. config:setting:: web-tlskeyfile - :displayname: TLS key file (Web Server) - :systemconsole: Environment > Web Server - :configjson: .ServiceSettings.TLSKeyFile - :environment: MM_SERVICESETTINGS_TLSKEYFILE - :description: The path to the TLS key file to use for TLS connection security. - -TLS key file -~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+--------------------------------------------------------+---------------------------------------------------------------+ -| The path to the TLS key file to use for TLS | - System Config path: **Environment > Web Server** | -| connection security. | - ``config.json`` setting: ``".ServiceSettings.TLSKeyFile",`` | -| | - Environment variable: ``MM_SERVICESETTINGS_TLSKEYFILE`` | -| String input. | | -+--------------------------------------------------------+---------------------------------------------------------------+ - -.. config:setting:: web-useletsencrypt - :displayname: Use Let's Encrypt (Web Server) - :systemconsole: Environment > Web Server - :configjson: .ServiceSettings.UseLetsEncrypt - :environment: MM_SERVICESETTINGS_USELETSENCRYPT - :description: Enable the automatic retrieval of certificates from Let’s Encrypt. - - - **true**: The certificate will be retrieved when a client attempts to connect from a new domain. This will work with multiple domains. - - **false**: **(Default)** Manual certificate specification based on the TLS Certificate File and TLS Key File specified above. - -Use Let's Encrypt -~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+-----------------------------------------------------------------------------------------------+--------------------------------------------------------------------------+ -| Enable the automatic retrieval of certificates from Let’s Encrypt. | - System Config path: **Environment > Web Server** | -| See the :doc:`configuring TLS on Mattermost documentation ` | - ``config.json`` setting: ``".ServiceSettings.UseLetsEncrypt: false",`` | -| for more details on setting up Let’s Encrypt. | - Environment variable: ``MM_SERVICESETTINGS_USELETSENCRYPT`` | -| | | -| - **true**: The certificate will be retrieved when a client | | -| attempts to connect from a new domain. This will work with | | -| multiple domains. | | -| - **false**: **(Default)** Manual certificate specification | | -| based on the TLS Certificate File and TLS Key File specified | | -| above. | | -+-----------------------------------------------------------------------------------------------+--------------------------------------------------------------------------+ - -.. config:setting:: web-letsencryptcache - :displayname: Let's Encrypt certificate cache file (Web Server) - :systemconsole: Environment > Web Server - :configjson: .ServiceSettings.LetsEncryptCertificateCacheFile - :environment: MM_SERVICESETTINGS_LETSENCRYPTCERTIFICATECACHEFILE - :description: The path to the file where certificates and other data about the Let’s Encrypt service will be stored. - -Let's Encrypt certificate cache file -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+--------------------------------------------------------+------------------------------------------------------------------------------------+ -| The path to the file where certificates and other data | - System Config path: **Environment > Web Server** | -| about the Let’s Encrypt service will be stored. | - ``config.json`` setting: ``".ServiceSettings.LetsEncryptCertificateCacheFile",`` | -| | - Environment variable: ``MM_SERVICESETTINGS_LETSENCRYPTCERTIFICATECACHEFILE`` | -| File path input. | | -+--------------------------------------------------------+------------------------------------------------------------------------------------+ - -.. config:setting:: web-readtimeout - :displayname: Read timeout (Web Server) - :systemconsole: Environment > Web Server - :configjson: .ServiceSettings.ReadTimeout - :environment: MM_SERVICESETTINGS_READTIMEOUT - :description: Maximum time allowed from when the connection is accepted to when the request body is fully read. Default is **300** seconds. - -Read timeout -~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------+---------------------------------------------------------------------+ -| Maximum time allowed from when the connection is | - System Config path: **Environment > Web Server** | -| accepted to when the request body is fully read. | - ``config.json`` setting: ``".ServiceSettings.ReadTimeout: 300",`` | -| | - Environment variable: ``MM_SERVICESETTINGS_READTIMEOUT`` | -| Numerical input in seconds. Default is **300** seconds. | | -+---------------------------------------------------------+---------------------------------------------------------------------+ - -.. config:setting:: web-writetimeout - :displayname: Write timeout (Web Server) - :systemconsole: Environment > Web Server - :configjson: .ServiceSettings.WriteTimeout - :environment: MM_SERVICESETTINGS_WRITETIMEOUT - - If using HTTP (insecure), this is the maximum time, in seconds, allowed from the end of reading the request headers until the response is written. - If using HTTPS, it's the total time, in seconds, from when the connection is accepted until the response is written. - Default is 300 seconds. - -Write timeout -~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+----------------------------------------------------------+-----------------------------------------------------------------------------+ -| - If using HTTP (insecure), this is the maximum time | - System Config path: **Environment > Web Server** | -| allowed from the end of reading the request headers | - ``config.json`` setting: ``".ServiceSettings.WriteTimeout: 300",`` | -| until the response is written. | - Environment variable: ``MM_SERVICESETTINGS_WRITETIMEOUT`` | -| - If using HTTPS, it's the total time from when the | | -| connection is accepted until the response is written. | | -| | | -| Numerical input in seconds. Default is **300** seconds. | | -+----------------------------------------------------------+-----------------------------------------------------------------------------+ - -.. config:setting:: web-idletimeout - :displayname: Idle timeout (Web Server) - :systemconsole: Environment > Web Server - :configjson: .ServiceSettings.IdleTimeout - :environment: MM_SERVICESETTINGS_IDLETIMEOUT - :description: This is the maximum time, in seconds, allowed before an idle connection is disconnected. Default is **300** seconds. - -Idle timeout -~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------+---------------------------------------------------------------------+ -| Set an explicit idle timeout in the HTTP server. | - System Config path: **Environment > Web Server** | -| This is the maximum time allowed before an idle | - ``config.json`` setting: ``".ServiceSettings.IdleTimeout: 300",`` | -| connection is disconnected. | - Environment variable: ``MM_SERVICESETTINGS_IDLETIMEOUT`` | -| | | -| Numerical input in seconds. Default is **300** seconds. | | -+---------------------------------------------------------+---------------------------------------------------------------------+ - -.. config:setting:: web-webservermode - :displayname: Webserver mode (Web Server) - :systemconsole: Environment > Web Server - :configjson: .ServiceSettings.WebserverMode - :environment: MM_SERVICESETTINGS_WEBSERVERMODE - - - **gzip**: **(Default)** The Mattermost server will serve static files compressed with gzip to improve performance. - - **Uncompressed**: The Mattermost server will serve static files uncompressed. - - **Disabled**: The Mattermost server will not serve static files. - -Webserver mode -~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------------+------------------------------------------------------------------------+ -| We recommend gzip to improve performance unless your | - System Config path: **Environment > Web Server** | -| environment has specific restrictions, such as a web proxy that | - ``config.json`` setting: ``".ServiceSettings.WebserverMode: gzip",`` | -| distributes gzip files poorly. | - Environment variable: ``MM_SERVICESETTINGS_WEBSERVERMODE`` | -| | | -| - **gzip**: **(Default)** The Mattermost server will serve static | | -| files compressed with gzip to improve performance. | | -| gzip compression applies to the HTML, CSS, Javascript, and other | | -| static content files that make up the Mattermost web client. | | -| - **Uncompressed**: The Mattermost server will serve static | | -| files uncompressed. | | -| - **Disabled**: The Mattermost server will not serve static files. | | -+---------------------------------------------------------------------+------------------------------------------------------------------------+ - -.. config:setting:: web-insecureoutgoingconnections - :displayname: Enable insecure outgoing connections (Web Server) - :systemconsole: Environment > Web Server - :configjson: .ServiceSettings.EnableInsecureOutgoingConnections - :environment: MM_SERVICESETTINGS_ENABLEINSECUREOUTGOINGCONNECTIONS - - - **true**: Outgoing HTTPS requests, including S3 clients, can accept unverified, self-signed certificates. - - **false**: **(Default)** Only secure HTTPS requests are allowed. - -Enable insecure outgoing connections -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+ -| Configure Mattermost to allow insecure outgoing connections. | - System Config path: **Environment > Web Server** | -| | - ``config.json`` setting: ``".ServiceSettings.EnableInsecureOutgoingConnections: false",`` | -| - **true**: Outgoing HTTPS requests, including S3 clients, | - Environment variable: ``MM_SERVICESETTINGS_ENABLEINSECUREOUTGOINGCONNECTIONS`` | -| can accept unverified, self-signed certificates. | | -| For example, outgoing webhooks to a server with a | | -| self-signed TLS certificate, using any domain, will be | | -| allowed, and will skip TLS verification. | | -| - **false**: **(Default)** Only secure HTTPS requests are | | -| allowed. | | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+ -| **Security note**: Enabling this feature makes these connections susceptible to man-in-the-middle attacks. | -+---------------------------------------------------------------+---------------------------------------------------------------------------------------------+ - -.. config:setting:: web-managedresourcepaths - :displayname: Managed resource paths (Web Server) - :systemconsole: Environment > Web Server - :configjson: .ServiceSettings.ManagedResourcePaths - :environment: MM_SERVICESETTINGS_MANAGEDRESOURCEPATHS - :description: A comma-separated list of paths within the Mattermost domain that are managed by a third party service instead of Mattermost itself. - -Managed resource paths -~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+--------------------------------------------------------+-------------------------------------------------------------------------+ -| A comma-separated list of paths within the Mattermost | - System Config path: **Environment > Web Server** | -| domain that are managed by a third party service | - ``config.json`` setting: ``".ServiceSettings.ManagedResourcePaths",`` | -| instead of Mattermost itself. | - Environment variable: ``MM_SERVICESETTINGS_MANAGEDRESOURCEPATHS`` | -| | | -| Links to these paths will be opened in a new | | -| tab/window by Mattermost apps. | | -| | | -| For example, if Mattermost is running on | | -| ``https://mymattermost.com``, setting this to | | -| conference will cause links such as | | -| ``https://mymattermost.com/conference`` to open in a | | -| new window. | | -+--------------------------------------------------------+-------------------------------------------------------------------------+ -| **Note:** | -| When using the Mattermost Desktop App, additional configuration is required to open the link within the Desktop App instead of | -| in a browser. See the :doc:`desktop managed resources ` | -| documentation for details. | -+--------------------------------------------------------+-------------------------------------------------------------------------+ - -Reload configuration from disk -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: ../_static/badges/ent-only.rst - :start-after: :nosearch: - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+----------------------------------------------------------+---------------------------------------------------------------+ -| You must change the database line in the ``config.json`` | - System Config path: **Environment > Web Server** | -| file, and then reload configuration to fail over | - ``config.json`` setting: N/A | -| without taking the server down. | - Environment variable: N/A | -| | | -| Select the **Reload configuration from disk** button | | -| in the System Console after changing your database | | -| configuration. Then, go to **Environment > Database** | | -| and select **Recycle Database Connections** to | | -| complete the reload. | | -+----------------------------------------------------------+---------------------------------------------------------------+ - -Purge all caches -~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+----------------------------------------------------------+---------------------------------------------------------------+ -| Purge all in-memory caches for sessions, accounts, | - System Config path: **Environment > Web Server** | -| and channels. | - ``config.json`` setting: N/A | -| | - Environment variable: N/A | -| Select the **Purge All Caches** button in the System | | -| Console to purge all caches. | | -+----------------------------------------------------------+---------------------------------------------------------------+ -| **Note**: Purging the caches may adversely impact performance. | -| :doc:`high availability cluster-based deployments ` will attempt | -| to purge all the servers in the cluster | -+----------------------------------------------------------+---------------------------------------------------------------+ - -.. config:setting:: web-websocketurl - :displayname: Websocket URL (Web Server) - :systemconsole: N/A - :configjson: .ServiceSettings.WebsocketURL - :environment: MM_SERVICESETTINGS_WEBSOCKETURL - :description: You can configure the server to instruct clients on where they should try to connect websockets to. - -Websocket URL -~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+--------------------------------------------------------+---------------------------------------------------------------------+ -| You can configure the server to instruct clients | - System Config path: N/A | -| on where they should try to connect websockets to. | - ``config.json`` setting: ``".ServiceSettings.WebsocketURL: "",`` | -| | - Environment variable: ``MM_SERVICESETTINGS_WEBSOCKETURL`` | -| String input. | | -+--------------------------------------------------------+---------------------------------------------------------------------+ -| **Note**: We strongly recommend configuring a single websocket URL that matches the `Site URL <#site-url>`_ configuration | -| setting. | -+--------------------------------------------------------+---------------------------------------------------------------------+ - -.. config:setting:: web-licensefilelocation - :displayname: License file location (Web Server) - :systemconsole: N/A - :configjson: .ServiceSettings.LicenseFileLocation - :environment: MM_SERVICESETTINGS_LICENSEFILELOCATION - :description: The path and filename of the license file on disk. - -License file location -~~~~~~~~~~~~~~~~~~~~~ - -.. include:: ../_static/badges/ent-pro-only.rst - :start-after: :nosearch: - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+--------------------------------------------------------+----------------------------------------------------------------------------+ -| The path and filename of the license file on disk. | - System Config path: N/A | -| On startup, if Mattermost can't find a valid license | - ``config.json`` setting: ``".ServiceSettings.LicenseFileLocation: "",`` | -| in the database from a previous upload, it looks in | - Environment variable: ``MM_SERVICESETTINGS_LICENSEFILELOCATION`` | -| this path for the license file. | | -| | | -| String input. Can be an absolute path or a path | | -| relative to the ``mattermost`` directory. | | -+--------------------------------------------------------+----------------------------------------------------------------------------+ - -.. config:setting:: web-tlsminimumversion - :displayname: TLS minimum version (Web Server) - :systemconsole: N/A - :configjson: .ServiceSettings.TLSMinVer - :environment: MM_SERVICESETTINGS_TLSMINVER - :description: The minimum TLS version used by the Mattermost server. Default value is **1.2**. - -TLS minimum version -~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+--------------------------------------------------------+---------------------------------------------------------------------+ -| The minimum TLS version used by the Mattermost server. | - System Config path: N/A | -| | - ``config.json`` setting: ``".ServiceSettings.TLSMinVer: 1.2",`` | -| String input. Default is **1.2**. | - Environment variable: ``MM_SERVICESETTINGS_TLSMINVER`` | -+--------------------------------------------------------+---------------------------------------------------------------------+ -| **Note**: This setting only takes effect if you are using the built-in server binary directly, and not using a reverse proxy | -| layer, such as NGINX. | -+--------------------------------------------------------+---------------------------------------------------------------------+ - -.. config:setting:: web-trustedproxyipheader - :displayname: Trusted proxy IP header (Web Server) - :systemconsole: N/A - :configjson: .ServiceSettings.TrustedProxyIPHeader - :environment: MM_SERVICESETTINGS_TRUSTEDPROXYIPHEADER - :description: Specified headers that will be checked, one by one, for IP addresses (order is important). All other headers are ignored. - -Trusted proxy IP header -~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+--------------------------------------------------------+------------------------------------------------------------------------------+ -| Specified headers that will be checked, one by one, | - System Config path: N/A | -| for IP addresses (order is important). | - ``config.json`` setting: ``".ServiceSettings.TrustedProxyIPHeader: []",`` | -| All other headers are ignored. | - Environment variable: ``MM_SERVICESETTINGS_TRUSTEDPROXYIPHEADER`` | -| | | -| String array input consisting of header names, | | -| such as ``["X-Forwarded-For", "X-Real-Ip"]``. | | -+--------------------------------------------------------+------------------------------------------------------------------------------+ -| **Notes**: | -| | -| - The default value of ``[]`` means that no header will be trusted. Prior to v5.12, the absence of this configuration setting entry | -| will have it set to ``["X-Forwarded-For", "X-Real-Ip"]`` on upgrade to maintain backwards compatibility. | -| - We recommend keeping the default setting when Mattermost is running without a proxy to avoid the client sending the headers and | -| bypassing rate limiting and/or the audit log. | -| - For environments that use a reverse proxy, this issue does not exist, provided that the headers are set by the reverse proxy. | -| In those environments, only explicitly whitelist the header set by the reverse proxy and no additional values. | -| | -| | -+--------------------------------------------------------+------------------------------------------------------------------------------+ - -.. config:setting:: web-enablehsts - :displayname: Enable Strict Transport Security (HSTS) (Web Server) - :systemconsole: N/A - :configjson: .ServiceSettings.TLSStrictTransport - :environment: MM_SERVICESETTINGS_TLSSTRICTTRANSPORT - - - **true**: Adds the Strict Transport Security (HSTS) header to all responses, forcing the browser to request all resources via HTTPS. - - **false**: **(Default)** No restrictions on TLS transport. Strict Transport Security (HSTS) header isn't added to responses. - -Enable Strict Transport Security (HSTS) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+--------------------------------------------------------+-------------------------------------------------------------------------------+ -| - **true**: Adds the Strict Transport Security (HSTS) | - System Config path: N/A | -| header to all responses, forcing the browser to | - ``config.json`` setting: ``".ServiceSettings.TLSStrictTransport: false",`` | -| request all resources via HTTPS. | - Environment variable: ``MM_SERVICESETTINGS_TLSSTRICTTRANSPORT`` | -| - **false**: **(Default)** No restrictions on TLS | | -| transport. Strict Transport Security (HSTS) header | | -| isn't added to responses. | | -+--------------------------------------------------------+-------------------------------------------------------------------------------+ -| See the `Strict-Transport-Security `__ | -| documentation for details. | -+--------------------------------------------------------+-------------------------------------------------------------------------------+ - -.. config:setting:: web-securetlstransportexpiry - :displayname: Secure TLS transport expiry (Web Server) - :systemconsole: N/A - :configjson: .ServiceSettings.TLSStrictTransportMaxAge - :environment: MM_SERVICESETTINGS_TLSSTRICTTRANSPORTMAXAGE - :description: The time, in seconds, that the browser remembers a site is only to be accessed using HTTPS. Default is **63072000** seconds (2 years). - -Secure TLS transport expiry -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+--------------------------------------------------------+----------------------------------------------------------------------------------------+ -| The time, in seconds, that the browser remembers a | - System Config path: N/A | -| site is only to be accessed using HTTPS. After this | - ``config.json`` setting: ``".ServiceSettings.TLSStrictTransportMaxAge: 63072000",`` | -| period, a site can't be accessed using HTTP unless | - Environment variable: ``MM_SERVICESETTINGS_TLSSTRICTTRANSPORTMAXAGE`` | -| ``TLSStrictTransport`` is set to ``true``. | | -| | | -| Numerical input. Default is **63072000** (2 years). | | -+--------------------------------------------------------+----------------------------------------------------------------------------------------+ -| See the `Strict-Transport-Security `__ | -| documentation for details. | -+--------------------------------------------------------+----------------------------------------------------------------------------------------+ - -.. config:setting:: web-tlscipheroverwrites - :displayname: TLS cipher overwrites (Web Server) - :systemconsole: N/A - :configjson: .ServiceSettings.TLSOverwriteCiphers - :environment: MM_SERVICESETTINGS_TLSOVERWRITECIPHERS - :description: Set TLS ciphers overwrites to meet requirements from legacy clients which don't support modern ciphers, or to limit the types of accepted ciphers. - -TLS cipher overwrites -~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+--------------------------------------------------------+-----------------------------------------------------------------------------+ -| Set TLS ciphers overwrites to meet requirements from | - System Config path: N/A | -| legacy clients which don't support modern ciphers, | - ``config.json`` setting: ``".ServiceSettings.TLSOverwriteCiphers: []",`` | -| or to limit the types of accepted ciphers. | - Environment variable: ``MM_SERVICESETTINGS_TLSOVERWRITECIPHERS`` | -| | | -| If none specified, the Mattermost server assumes a | | -| set of currently considered secure ciphers, and allows | | -| overwrites in the edge case. | | -| | | -| String array input. | | -+--------------------------------------------------------+-----------------------------------------------------------------------------+ -| **Notes**: | -| | -| - This setting only takes effect if you are using the built-in server binary directly, and not using a reverse proxy layer, such | -| as NGINX. | -| - See the ``ServerTLSSupportedCiphers`` variable in `/model/config.go | -| `__ for a list of ciphers considered secure. | -+--------------------------------------------------------+-----------------------------------------------------------------------------+ - -.. config:setting:: web-goroutinehealththreshold - :displayname: Goroutine health threshold (Web Server) - :systemconsole: N/A - :configjson: .ServiceSettings.GoroutineHealthThreshold - :environment: MM_SERVICESETTINGS_GOROUTINEHEALTHTHRESHOLD - :description: Set a threshold on the number of goroutines when the Mattermost system is considered to be in a healthy state. Default is **-1** which turns off checking for the threshold. - -Goroutine health threshold -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+--------------------------------------------------------+----------------------------------------------------------------------------------+ -| Set a threshold on the number of goroutines when the | - System Config path: N/A | -| Mattermost system is considered to be in a healthy | - ``config.json`` setting: ``".ServiceSettings.GoroutineHealthThreshold: -1",`` | -| state. | - Environment variable: ``MM_SERVICESETTINGS_GOROUTINEHEALTHTHRESHOLD`` | -| | | -| When goroutines exceed this limit, a warning is | | -| returned in the server logs. | | -| | | -| Numeric input. Default is **-1** which turns off | | -| checking for the threshold. | | -+--------------------------------------------------------+----------------------------------------------------------------------------------+ - -.. config:setting:: web-allowcookiesforsubdomains - :displayname: Allow cookies for subdomains (Web Server) - :systemconsole: N/A - :configjson: .ServiceSettings.AllowCookiesForSubdomains - :environment: MM_SERVICESETTINGS_ALLOWCOOKIESFORSUBDOMAINS - - - **true**: **(Default)** Allows cookies for subdomains by setting the domain parameter on Mattermost cookies. - - **false**: Cookies not allowed for subdomains. - -Allow cookies for subdomains -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E10 or E20

- -+--------------------------------------------------------+-------------------------------------------------------------------------------------+ -| - **true**: **(Default)** Allows cookies for | - System Config path: N/A | -| subdomains by setting the domain parameter on | - ``config.json`` setting: ``".ServiceSettings.AllowCookiesForSubdomains: true",`` | -| Mattermost cookies. | - Environment variable: ``MM_SERVICESETTINGS_ALLOWCOOKIESFORSUBDOMAINS`` | -| - **false**: Cookies not allowed for subdomains. | | -+--------------------------------------------------------+-------------------------------------------------------------------------------------+ - -.. config:setting:: web-clusterlogtimeout - :displayname: Cluster log timeout (Web Server) - :systemconsole: N/A - :configjson: .ServiceSettings.ClusterLogTimeoutMilliseconds - :environment: MM_SERVICESETTINGS_CLUSTERLOGTIMEOUTMILLISECONDS - :description: Define the frequency, in milliseconds, of cluster request time logging for performance monitoring. Default is **2000** milliseconds (2 seconds). - -Cluster log timeout -~~~~~~~~~~~~~~~~~~~ - -.. include:: ../_static/badges/ent-only.rst - :start-after: :nosearch: - -.. raw:: html - -

Also available in legacy Mattermost Enterprise Edition E20

- -+--------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| Define the frequency, in milliseconds, of cluster | - System Config path: N/A | -| request time logging for performance monitoring. | - ``config.json`` setting: ``".ServiceSettings.ClusterLogTimeoutMilliseconds: 2000",`` | -| | - Environment variable: ``MM_SERVICESETTINGS_CLUSTERLOGTIMEOUTMILLISECONDS`` | -| | | -| Numerical input. Default is **2000** milliseconds | | -| (2 seconds). | | -+--------------------------------------------------------+-----------------------------------------------------------------------------------------+ -| See the :doc:`performance monitoring ` documentation for details. | -+--------------------------------------------------------+-----------------------------------------------------------------------------------------+ - -.. config:setting:: service-maxpayloadsize - :displayname: Maximum payload size (File Storage) - :systemconsole: N/A - :configjson: .ServiceSettings.MaximumPayloadSizeBytes - :environment: MM_SERVICESETTINGS_MAXIMUMPAYLOADSIZEBYTES - :description: The maximum payload size in bytes for all APIs except APIs that receive a file as an input. For example, the upload attachment API or the API to upload a custom emoji. Default is 300000. - -Maximum payload size -~~~~~~~~~~~~~~~~~~~~ - -+-----------------------------------------------------------+-------------------------------------------------------------------------------------+ -| The maximum payload size in bytes for all APIs except | - System Config path: N/A | -| APIs that receive a file as an input. | - ``config.json`` setting: ``".ServiceSettings.MaximumPayloadSizeBytes: 300000",`` | -| | - Environment variable: ``MM_SERVICESETTINGS_MAXIMUMPAYLOADSIZEBYTES`` | -| For example, the upload attachment API or the API to | | -| upload a custom emoji. | | -| | | -| Numerical value. Default is **300000** (300 kB). | | -+-----------------------------------------------------------+-------------------------------------------------------------------------------------+ diff --git a/source/deploy/mobile-troubleshoot.rst b/source/deploy/mobile-troubleshoot.rst index 29b8b1f2435..78a034dc4bc 100644 --- a/source/deploy/mobile-troubleshoot.rst +++ b/source/deploy/mobile-troubleshoot.rst @@ -10,7 +10,7 @@ If the server URL is correct, there could be an issue with the SSL certificate c To check your SSL certificate set up, test it by visiting a site such as `SSL Labs `__. If there’s an error about the missing chain or certificate path, there is likely an intermediate certificate missing that needs to be included. -Please note that the apps cannot connect to servers with self-signed certificates, consider using :doc:`Let's Encrypt ` instead. +Please note that the apps cannot connect to servers with self-signed certificates, consider using :ref:`Let's Encrypt ` instead. Login with ADFS/Office365 is not working ---------------------------------------- diff --git a/source/install/common-deploy-faq.rst b/source/install/common-deploy-faq.rst index 51dcdf9a142..0bfec1af776 100644 --- a/source/install/common-deploy-faq.rst +++ b/source/install/common-deploy-faq.rst @@ -1,6 +1,8 @@ :orphan: :nosearch: +.. This page is intentionally not accessible via the LHS navigation pane because it's common content included on other docs pages. + Why doesn't Mattermost start at system boot? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/install/common-local-deploy-docker.rst b/source/install/common-local-deploy-docker.rst deleted file mode 100644 index 027428ff30c..00000000000 --- a/source/install/common-local-deploy-docker.rst +++ /dev/null @@ -1,29 +0,0 @@ -:orphan: -:nosearch: - -.. This page is intentionally not accessible via the LHS navigation pane because it's common content included on other docs pages. - -Preview Mattermost using Docker -------------------------------- - -Using the `Mattermost Docker Preview Image `__ is the fastest way to trial Mattermost in **Preview Mode**, and explore product functionality on a single local machine. - -.. important:: - - This local image is self-contained (i.e., it has an internal database and works out of the box). Dropping a container using this image removes data and configuration as expected. You can see the :doc:`configuration settings ` documentation to learn more about customizing your trial deployment. - - **Preview Mode** shouldn't be used in a production environment, as it uses a known password string, contains other non-production configuration settings, has email disabled, keeps no persistent data (all data lives inside the container), and doesn't support upgrades. - - If you are planning to use the calling functionality in **Preview Mode** on a non-local environment, you should ensure that the server is running on a secure (HTTPs) connection and that the :ref:`network requirements ` to run calls are met. - -1. Install `Docker `__. - -2. Once you have Docker, run the following command in a terminal window: - - .. code-block:: sh - - docker run --name mattermost-preview -d --publish 8065:8065 --publish 8443:8443 mattermost/mattermost-preview - -3. When Docker is done fetching the image, navigate to ``http://localhost:8065/`` in your browser to preview Mattermost. -4. Select **Don't have an account** in the top right corner of the screen to create an account for your preview instance. If you don't see this option, ensure that the :ref:`Enable open server ` configuration setting is enabled. This setting is disabled for self-hosted Mattermost deployments by default. -5. Log in to your preview instance with your user credentials. diff --git a/source/install/common-prod-deploy-docker.rst b/source/install/common-prod-deploy-docker.rst deleted file mode 100644 index e77bb81b113..00000000000 --- a/source/install/common-prod-deploy-docker.rst +++ /dev/null @@ -1,113 +0,0 @@ -:orphan: -:nosearch: - -.. This page is intentionally not accessible via the LHS navigation pane because it's common content included on other docs pages. - -You'll need `Docker Engine `__ and `Docker Compose `__ (release 1.28 or later). - -.. important:: - - - The production configuration results in two separate containers: one for the database and one for the application. An optional third container results when using NGINX for reverse proxy. - - Encountering issues with your Docker deployment? See the :ref:`Docker deployment troubleshooting ` documentation for details. - -To deploy Mattermost on Docker: - -1. In a terminal window, clone the repository and enter the directory. - - .. code-block:: sh - - git clone https://github.com/mattermost/docker - cd docker - -2. Create your ``.env`` file by copying and adjusting the ``env.example`` file. - - .. code-block:: sh - - cp env.example .env - -.. important:: - - At a minimum, you must edit the ``DOMAIN`` value in the ``.env`` file to correspond to the domain for your Mattermost server. - -3. Create the required directories and set their permissions. - - .. code-block:: sh - - mkdir -p ./volumes/app/mattermost/{config,data,logs,plugins,client/plugins,bleve-indexes} - sudo chown -R 2000:2000 ./volumes/app/mattermost - -4. Configure TLS for NGINX *(optional)*. If you're not using the included NGINX reverse proxy, you can skip this step. - - **If creating a new certificate and key:** - - .. code-block:: sh - - bash scripts/issue-certificate.sh -d -o ${PWD}/certs - - To include the certificate and key, uncomment the following lines in your ``.env`` file and ensure they point to the appropriate files. - - .. code-block:: sh - - #CERT_PATH=./certs/etc/letsencrypt/live/${DOMAIN}/fullchain.pem - #KEY_PATH=./certs/etc/letsencrypt/live/${DOMAIN}/privkey.pem - - **If using a pre-existing certificate and key:** - - .. code-block:: sh - - mkdir -p ./volumes/web/cert - cp .pem ./volumes/web/cert/cert.pem - cp .pem ./volumes/web/cert/key-no-password.pem - - To include the certificate and key, ensure the following lines in your ``.env`` file points to the appropriate files. - - .. code-block:: sh - - CERT_PATH=./volumes/web/cert/cert.pem - KEY_PATH=./volumes/web/cert/key-no-password.pem - -5. Configure SSO with GitLab *(optional)*. If you want to use SSO with GitLab, and you're using a self-signed certificate, you have to add the PKI chain for your authority. This is required to avoid the ``Token request failed: certificate signed by unknown authority`` error. - - To add the PKI chain, uncomment this line in your ``.env`` file, and ensure it points to your ``pki_chain.pem`` file: - - .. code-block:: sh - - #GITLAB_PKI_CHAIN_PATH=/pki_chain.pem - - Then uncomment this line in your ``docker-compose.yml`` file, and ensure it points to the same ``pki_chain.pem`` file: - - .. code-block:: sh - - # - ${GITLAB_PKI_CHAIN_PATH}:/etc/ssl/certs/pki_chain.pem:ro - -6. Deploy Mattermost. - - **Without using the included NGINX:** - - .. code-block:: sh - - sudo docker compose -f docker-compose.yml -f docker-compose.without-nginx.yml up -d - - To access your new Mattermost deployment, navigate to ``http://:8065/`` in your browser. - - To shut down your deployment: - - .. code-block:: sh - - sudo docker compose -f docker-compose.yml -f docker-compose.without-nginx.yml down - - **Using the included NGINX:** - - .. code-block:: sh - - sudo docker compose -f docker-compose.yml -f docker-compose.nginx.yml up -d - - To access your new Mattermost deployment via HTTPS, navigate to ``https:///`` in your browser. - - To shut down your deployment: - - .. code-block:: sh - - sudo docker compose -f docker-compose.yml -f docker-compose.nginx.yml down - -7. Create your first Mattermost system admin user, :doc:`invite more users `, and explore the Mattermost platform. \ No newline at end of file diff --git a/source/install/common-prod-deploy-omnibus.rst b/source/install/common-prod-deploy-omnibus.rst deleted file mode 100644 index 7371049ab4c..00000000000 --- a/source/install/common-prod-deploy-omnibus.rst +++ /dev/null @@ -1,55 +0,0 @@ -:orphan: -:nosearch: - -.. This page is intentionally not accessible via the LHS navigation pane because it's being phased out in favor of a dedicated Tarball deploy page linked to the /download page of the website. - -Mattermost bundles the components of a Mattermost deployment into a single installation, called **Omnibus**. Mattermost Omnibus currently supports Ubuntu's ``focal`` (20.04), ``jammy`` (22.04), and ``noble`` (24.04) distributions. The package bundles the free, unlicensed Mattermost Enterprise version of Mattermost, and leverages the `apt package manager `__ to install and update the platform components. A custom CLI and ansible recipes link the components together and configures them. - -**Minimum system requirements** - -- Hardware: 2 vCPUs/cores with 4GB RAM (support for 1,000-2,000 users) -- Database: PostgreSQL v12+ -- Network ports required: - - - Application ports 80/443, TLS, TCP Inbound - - Administrator Console port 8065, TLS, TCP Inbound - - SMTP port 10025, TCP/UDP Outbound - -**Deploy Omnibus** - -1. In a terminal window, run the following command to configure the repositories needed for a PostgreSQL database, configure an NGINX web server to act as a proxy, configure certbot to issue and renew the SSL certificate, and configure the Mattermost Omnibus repository so that you can run the install command. - - .. code-block:: sh - - curl -o- https://deb.packages.mattermost.com/repo-setup.sh | sudo bash - -2. Install the Omnibus package. - - .. code-block:: sh - - sudo apt install mattermost-omnibus -y - - To issue the certificate, the installer requests a domain name and an email address from you. These are used to generate the certificate and deliver any related communications. After all the packages are installed, Omnibus runs ansible scripts that configure all the platform components and starts the server. - - .. note:: - - If you encounter ``EXPKEYSIG``, this indicates that the certificate is expired. To obtain a new certificate, run the following commands: - - .. code-block:: sh - - sudo apt-key remove 44774B28 - sudo curl -o- https://deb.packages.mattermost.com/pubkey.gpg | sudo apt-key add - - sudo apt update - -3. Open a browser and navigate to your Mattermost domain either by domain name (e.g. ``mymattermostserver.com``), or by the server's IP address if you're not using a domain name. - -4. Create your first Mattermost user, :doc:`invite more users `, and explore the Mattermost platform. - - .. note:: - - We recommend installing and configuring Omnibus with SSL enabled; however, you can run the following command to disable SSL: ``sudo MMO_HTTPS=false apt install mattermost-omnibus``. - -Update Mattermost Omnibus -------------------------- - -Mattermost Omnibus is integrated with the apt package manager. When a new Mattermost version is released, run: ``sudo apt update && sudo apt upgrade`` to download and update your Mattermost instance. diff --git a/source/install/common-prod-deploy-tar.rst b/source/install/common-prod-deploy-tar.rst deleted file mode 100644 index 4db672e8207..00000000000 --- a/source/install/common-prod-deploy-tar.rst +++ /dev/null @@ -1,186 +0,0 @@ -:orphan: -:nosearch: - -.. This page is intentionally not accessible via the LHS navigation pane because it's being phased out in favor of a dedicated Tarball deploy page linked to the /download page of the website. - -.. include:: ../_static/badges/allplans-selfhosted.rst - :start-after: :nosearch: - -These instructions outline how to install Mattermost Server on a 64-bit Linux host from a compressed tarball, and assume the IP address of the Mattermost server is 10.10.10.2. - -**Minimum system requirements** - -- Hardware: 2 vCPUs/cores with 4GB RAM (support for 1,000-2,000 users) -- Database: PostgreSQL v12+ -- Network ports required: - - - Application ports 80/443, TLS, TCP Inbound - - Administrator Console port 8065, TLS, TCP Inbound - - SMTP port 10025, TCP/UDP Outbound - -**Deploy Generic Linux** - -1. Install and configure a PostgreSQL or MySQL database. See the following guides for details: - - - :doc:`Prepare your Mattermost PostgreSQL database ` - - :doc:`Prepare your Mattermost MySQL database ` - -2. Log in to the server that will host Mattermost Server and open a terminal window. - -3. Download :doc:`the latest version of the Mattermost Server `. In the following command, replace ``X.X.X`` with the version that you want to download: - - .. code-block:: sh - - # Enterprise Edition - wget https://releases.mattermost.com/X.X.X/mattermost-X.X.X-linux-amd64.tar.gz - - # Team Edition - wget https://releases.mattermost.com/X.X.X/mattermost-team-X.X.X-linux-amd64.tar.gz - -4. Extract the Mattermost Server files. - - .. code-block:: sh - - tar -xvzf mattermost*.gz - -5. Move the extracted file to the ``/opt`` directory. - - .. code-block:: sh - - sudo mv mattermost /opt - -6. Create the storage directory for files. - - .. code-block:: sh - - sudo mkdir /opt/mattermost/data - -.. note:: - - The storage directory will contain all the files and images that your users post to Mattermost, so you need to make sure that the drive is large enough to hold the anticipated number of uploaded files and images. - -7. Set up a system user and group called ``mattermost`` that will run this service, and set the ownership and permissions. - - a. Create the Mattermost user and group. - - .. code-block:: sh - - sudo useradd --system --user-group mattermost - - b. Set the user and group *mattermost* as the owner of the Mattermost files. - - .. code-block:: sh - - sudo chown -R mattermost:mattermost /opt/mattermost - - c. Give write permissions to the *mattermost* group. - - .. code-block:: sh - - sudo chmod -R g+w /opt/mattermost - -8. Set up the database driver in the file ``/opt/mattermost/config/config.json``. Open the file in a text editor and make the following changes: - - **If you're using PostgreSQL:** - - Set ``"DriverName"`` to ``"postgres"`` - Set ``"DataSource"`` to the following value, replacing ```` and ```` with the appropriate values: ``"postgres://mmuser:@:5432/mattermost?sslmode=disable&connect_timeout=10",`` - - **If you're using MySQL:** - - Set ``"DriverName"`` to ``"mysql"`` - Set ``"DataSource"`` to the following value, replacing ```` and ```` with the appropriate values. Also make sure that the database name is ``mattermost`` instead of ``mattermost_test``: ``"mmuser:@tcp(:3306)/mattermost?charset=utf8mb4,utf8&writeTimeout=30s"`` - -9. Test the Mattermost server to make sure everything works. - - a. Change to the Mattermost directory. - - .. code-block:: sh - - cd /opt/mattermost - - b. Start the Mattermost server as the user mattermost. - - .. code-block:: sh - - sudo -u mattermost bin/mattermost - - When the server starts, it shows some log information and the text ``Server is listening on :8065``. You can stop the server by pressing :kbd:`Ctrl` :kbd:`C` on Windows or Linux, or :kbd:`⌘` :kbd:`C` on Mac, in the terminal window. - -10. Set up Mattermost to use *systemd* for starting and stopping. - - a. Create a *systemd* unit file. - - .. code-block:: sh - - sudo touch /lib/systemd/system/mattermost.service - - b. Open the unit file as *root* in a text editor, and copy the following lines into the file. - - .. code-block:: text - - [Unit] - Description=Mattermost - After=network.target - After=postgresql.service - BindsTo=postgresql.service - [Service] - Type=notify - ExecStart=/opt/mattermost/bin/mattermost - TimeoutStartSec=3600 - KillMode=mixed - Restart=always - RestartSec=10 - WorkingDirectory=/opt/mattermost - User=mattermost - Group=mattermost - LimitNOFILE=49152 - [Install] - WantedBy=multi-user.target - - .. note:: - - * If you're using MySQL, replace ``postgresql.service`` with ``mysql.service`` in two places in the ``[Unit]`` section. - * If you've installed PostgreSQL or MySQL on a dedicated server, you need to remove the ``After=postgresql.service`` and ``BindsTo=postgresql.service`` or ``After=mysql.service`` and ``BindsTo=mysql.service`` lines in the ``[Unit]`` section or the Mattermost service won't start. - - c. Make systemd load the new unit. - - .. code-block:: sh - - sudo systemctl daemon-reload - - d. Check to make sure that the unit was loaded. - - .. code-block:: sh - - sudo systemctl status mattermost.service - - You should see an output similar to the following: - - .. code-block:: text - - mattermost.service - Mattermost - Loaded: loaded (/lib/systemd/system/mattermost.service; disabled; vendor preset: enabled) - Active: inactive (dead) - - e. Start the service. - - .. code-block:: sh - - sudo systemctl start mattermost.service - - f. Verify that Mattermost is running. - - .. code-block:: sh - - curl http://localhost:8065 - - You should see the HTML that's returned by the Mattermost server. If a firewall is used, external requests to port 8065 may be blocked. Use ``sudo ufw allow 8065`` to open port 8065. - - g. Set Mattermost to start on machine start up. - - .. code-block:: sh - - sudo systemctl enable mattermost.service - -Once your Mattermost server is up and running, create your first Mattermost user, :doc:`invite more users `, and explore the Mattermost platform. diff --git a/source/install/config-mattermost-server.rst b/source/install/config-mattermost-server.rst deleted file mode 100644 index e580c33c13d..00000000000 --- a/source/install/config-mattermost-server.rst +++ /dev/null @@ -1,55 +0,0 @@ -:orphan: -:nosearch: - -.. This page is intentionally not accessible via the LHS navigation pane because it's common content included on other docs pages. - -Configure Mattermost server ----------------------------- - -Create the system admin user and set up Mattermost for general use. - -1. Open a browser and navigate to your Mattermost instance. For example, if the IP address of the Mattermost server is ``10.10.10.2`` then go to ``http://10.10.10.2:8065``. - -2. Create the first team and user. The first user in the system has the ``system_admin`` role, which gives you access to the System Console. - -3. To open the System Console, select the Product menu in the top-left corner of the navigation panel, then select **System Console**. - -4. Set the site URL: - - * Open **System Console > Environment > Web Server**. - * In the **Site URL** field, set the URL that users point their browsers at. For example, *https://mattermost.example.com*. If you're using HTTPS, make sure that you set up TLS, either on Mattermost server or on a proxy. - -5. Set up email notifications. - - * In **Site Configuration > Notifications** make the following changes: - - - Set **Enable Email Notifications** to **true** - - Set **Notification Display Name** to **No-Reply** - - Set **Notification From Address** to *{your-domain-name}* For example, *example.com* - - * In **System Console > Environment > SMTP** make the following changes: - - - Set **SMTP Server Username** to *{SMTP-username}* For example, *admin@example.com* - - Set **SMTP Server Password** to *{SMTP-password}* - - Set **SMTP Server** to *{SMTP-server}* For example, *mail.example.com* - - Set **SMTP Server Port** to *465* - - Set **Connection Security** to *TLS* or *STARTTLS*, depending on what the SMTP server accepts - - * Select **Save** - * Select **Test Connection**. - -6. Open **System Console > Environment > File Storage** to set up the file and image storage location. - - * If you store the files locally, set **File Storage System** to *Local File System*, and then either accept the default for the **Local Storage Directory** or enter a location. The location must be a directory that exists and has write permissions for the Mattermost server. It can be an absolute path or a relative path. Relative paths are relative to the ``mattermost`` directory. - * If you store the files on Amazon S3, set **File Storage System** to *Amazon S3* and enter the appropriate values for your Amazon account. - -.. note:: - - * Files and images that users attach to their messages are not stored in the database. Instead, they're stored in a location that you specify, such as the local file system or in Amazon S3. - * Make sure that the location has enough free space. The amount of storage required depends on the number of users and the number and size of files that users attach to messages. - -7. Select **Save** to apply the configuration. - -8. Review and configure any other settings that may be applicable. - -9. Restart Mattermost by running ``sudo systemctl restart mattermost``. diff --git a/source/install/config-proxy-nginx.rst b/source/install/config-proxy-nginx.rst deleted file mode 100644 index 139e4ae8ba5..00000000000 --- a/source/install/config-proxy-nginx.rst +++ /dev/null @@ -1,132 +0,0 @@ -:orphan: -:nosearch: - -.. This page is intentionally not accessible via the LHS navigation pane because it's common content included on other docs pages. - -Configure NGINX as a proxy for Mattermost server ------------------------------------------------- - -NGINX is configured using a file in the ``/etc/nginx/sites-available`` directory. You need to create the file and then enable it. When creating the file, you need the IP address of your Mattermost server and the fully qualified domain name (FQDN) of your Mattermost website. - -1. Log in to the server that hosts NGINX and open a terminal window. -2. Create a configuration file for Mattermost by running the following command: - - ``sudo touch /etc/nginx/sites-available/mattermost`` on Ubuntu - ``sudo touch /etc/nginx/conf.d/mattermost`` on RHEL 8 - -3. Open the file ``/etc/nginx/sites-available/mattermost`` (Ubuntu) or ``/etc/nginx/conf.d/mattermost`` (RHEL 8) as *root* user in a text editor and replace its contents, if any, with the following lines. Make sure that you use your own values for the Mattermost server IP address and FQDN for *server_name*. - -SSL and HTTP/2 with server push are enabled in the provided configuration example. - - .. note:: - - - If you're going to use Let's Encrypt to manage your SSL certificate, stop at step 3 and see the :doc:`NGINX HTTP/2 and SSL product documentation ` for details. - - You'll need valid SSL certificates in order for NGINX to pin the certificates properly. Additionally, your browser must have permissions to accept the certificate as a valid CA-signed certificate. - - Note that the IP address included in the examples in this documentation may not match your network configuration. - - If you're running NGINX on the same machine as Mattermost, and NGINX resolves ``localhost`` to more than one IP address (IPv4 or IPv6), we recommend using ``127.0.0.1`` instead of ``localhost``. - - .. code-block:: text - - upstream backend { - server 10.10.10.2:8065; - keepalive 32; - } - - server { - listen 80 default_server; - server_name mattermost.example.com; - return 301 https://$server_name$request_uri; - } - - server { - listen 443 ssl http2; - listen [::]:443 ssl http2; - server_name mattermost.example.com; - - http2_push_preload on; # Enable HTTP/2 Server Push - - ssl_certificate /etc/letsencrypt/live/{domain-name}/fullchain.pem; - ssl_certificate_key /etc/letsencrypt/live/{domain-name}/privkey.pem; - ssl_session_timeout 1d; - - # Enable TLS versions (TLSv1.3 is required upcoming HTTP/3 QUIC). - ssl_protocols TLSv1.2 TLSv1.3; - - # Enable TLSv1.3's 0-RTT. Use $ssl_early_data when reverse proxying to - # prevent replay attacks. - # - # @see: https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_early_data - ssl_early_data on; - - ssl_ciphers 'ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384'; - ssl_prefer_server_ciphers on; - ssl_session_cache shared:SSL:50m; - # HSTS (ngx_http_headers_module is required) (15768000 seconds = six months) - add_header Strict-Transport-Security max-age=15768000; - # OCSP Stapling --- - # fetch OCSP records from URL in ssl_certificate and cache them - ssl_stapling on; - ssl_stapling_verify on; - - add_header X-Early-Data $tls1_3_early_data; - - location ~ /api/v[0-9]+/(users/)?websocket$ { - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection "upgrade"; - client_max_body_size 50M; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header X-Frame-Options SAMEORIGIN; - proxy_buffers 256 16k; - proxy_buffer_size 16k; - client_body_timeout 60s; - send_timeout 300s; - lingering_timeout 5s; - proxy_connect_timeout 90s; - proxy_send_timeout 300s; - proxy_read_timeout 90s; - proxy_http_version 1.1; - proxy_pass http://backend; - } - - location / { - client_max_body_size 100M; - proxy_set_header Connection ""; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header X-Frame-Options SAMEORIGIN; - proxy_buffers 256 16k; - proxy_buffer_size 16k; - proxy_read_timeout 600s; - proxy_http_version 1.1; - proxy_pass http://backend; - } - } - - # This block is useful for debugging TLS v1.3. Please feel free to remove this - # and use the `$ssl_early_data` variable exposed by NGINX directly should you - # wish to do so. - map $ssl_early_data $tls1_3_early_data { - "~." $ssl_early_data; - default ""; - } - -4. Remove the existing default sites-enabled file by running ``sudo rm /etc/nginx/sites-enabled/default`` (Ubuntu) or ``sudo rm /etc/nginx/conf.d/default`` (RHEL 8) - -5. Enable the mattermost configuration by running ``sudo ln -s /etc/nginx/sites-available/mattermost /etc/nginx/sites-enabled/mattermost`` (Ubuntu) or ``sudo ln -s /etc/nginx/conf.d/mattermost /etc/nginx/conf.d/default.conf`` (RHEL 8) - -6. Restart NGINX by running ``sudo systemctl restart nginx``. - -7. Verify that you can see Mattermost through the proxy by running ``curl https://localhost``. - - If everything is working, you will see the HTML for the Mattermost signup page. - -8. Restrict access to port 8065. - - By default, the Mattermost server accepts connections on port 8065 from every machine on the network. Use your firewall to deny connections on port 8065 to all machines except the machine that hosts NGINX and the machine that you use to administer the Mattermost server. If you're installing on Amazon Web Services, you can use Security Groups to restrict access. - -Now that NGINX is installed and running, you can configure it to use SSL, which allows you to use HTTPS connections and the HTTP/2 protocol. diff --git a/source/install/config-ssl-http2-nginx.rst b/source/install/config-ssl-http2-nginx.rst deleted file mode 100644 index e51452a9244..00000000000 --- a/source/install/config-ssl-http2-nginx.rst +++ /dev/null @@ -1,201 +0,0 @@ -:orphan: -:nosearch: - -.. This page is intentionally not accessible via the LHS navigation pane because it's common content included on other docs pages. - -Configure NGINX with SSL and HTTP/2 ------------------------------------ - -NGINX is configured using a file in the ``/etc/nginx/sites-available`` directory. You need to create the file and then enable it. When creating the file, you need the IP address of your Mattermost server and the fully qualified domain name (FQDN) of your Mattermost website. - -Using SSL gives greater security by ensuring that communications between Mattermost clients and the Mattermost server are encrypted. It also allows you to configure NGINX to use the HTTP/2 protocol. - -Although you can configure HTTP/2 without SSL, both Firefox and Chrome browsers support HTTP/2 on secure connections only. - -You can use any certificate that you want, but these instructions show you how to download and install certificates from `Let's Encrypt `__, a free certificate authority. - -.. note:: - - If Let’s Encrypt is enabled, forward port 80 through a firewall, with :ref:`Forward80To443 ` ``config.json`` setting set to ``true`` to complete the Let’s Encrypt certification. See the `Let's Encrypt/Certbot documentation `_ for additional assistance. - -1. Log in to the server that hosts NGINX and open a terminal window. - -2. Open the your Mattermost ``nginx.conf`` file as *root* in a text editor, then update the ``{ip}`` address in the ``upstream backend`` to point towards Mattermost (such as ``127.0.0.1:8065``), and update the ``server_name`` to be your domain for Mattermost. - - .. note:: - - - On Ubuntu this file is located at ``/etc/nginx/sites-available/``. If you don't have this file, run ``sudo touch /etc/nginx/sites-available/mattermost``. - - On CentOS/RHEL this file is located at ``/etc/nginx/conf.d/``. If you don't have this file, run ``sudo touch /etc/nginx/conf.d/mattermost``. - - The IP address included in the examples in this documentation may not match your network configuration. - - If you're running NGINX on the same machine as Mattermost, and NGINX resolves ``localhost`` to more than one IP address (IPv4 or IPv6), we recommend using ``127.0.0.1`` instead of ``localhost``. - - .. code-block:: text - - upstream backend { - server {ip}:8065; - keepalive 32; - } - - server { - listen 80 default_server; - server_name mattermost.example.com; - - location ~ /api/v[0-9]+/(users/)?websocket$ { - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection "upgrade"; - client_max_body_size 50M; - proxy_set_header Host $http_host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header X-Frame-Options SAMEORIGIN; - proxy_buffers 256 16k; - proxy_buffer_size 16k; - client_body_timeout 60s; - send_timeout 300s; - lingering_timeout 5s; - proxy_connect_timeout 90s; - proxy_send_timeout 300s; - proxy_read_timeout 90s; - proxy_pass http://backend; - } - - location / { - client_max_body_size 50M; - proxy_set_header Connection ""; - proxy_set_header Host $http_host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header X-Frame-Options SAMEORIGIN; - proxy_buffers 256 16k; - proxy_buffer_size 16k; - proxy_read_timeout 600s; - proxy_http_version 1.1; - proxy_pass http://backend; - } - } - - -3. Remove the existing default sites-enabled file by running ``sudo rm /etc/nginx/sites-enabled/default`` (Ubuntu) or ``sudo rm /etc/nginx/conf.d/default`` (RHEL 8). - -4. Enable the Mattermost configuration by running ``sudo ln -s /etc/nginx/sites-available/mattermost /etc/nginx/sites-enabled/mattermost`` (Ubuntu) or ``sudo ln -s /etc/nginx/conf.d/mattermost /etc/nginx/conf.d/default.conf`` (RHEL 8). - -5. Run ``sudo nginx -t`` to ensure your configuration is done properly. If you get an error, look into the NGINX config and make the needed changes to the file under ``/etc/nginx/sites-available/mattermost``. - -6. Restart NGINX by running ``sudo systemctl start nginx``. - -7. Verify that you can see Mattermost through the proxy by running ``curl http://localhost``. - - If everything is working, you will see the HTML for the Mattermost signup page. You will see invalid certificate when accessing through the IP or localhost. Use the full FQDN domain to verify if the SSL certificate has pinned properly and is valid. - -8. Install and update Snap by running ``sudo snap install core; sudo snap refresh core``. - -9. Install the Certbot package by running ``sudo snap install --classic certbot``. - -10. Add a symbolic link to ensure Certbot can run by running ``sudo ln -s /snap/bin/certbot /usr/bin/certbot``. - -11. Run the Let's Encrypt installer dry-run to ensure your DNS is configured properly by running ``sudo certbot certonly --dry-run``. - - This will prompt you to enter your email, accept the TOS, share your email, and select the domain you're activating certbot for. This will validate that your DNS points to this server properly and you are able to successfully generate a certificate. If this finishes successfully, proceed to step 12. - -12. Run the Let's Encrypt installer by running ``sudo certbot``. This will run certbot and will automatically edit your NGINX config file for the site(s) selected. - -13. Ensure your SSL is configured properly by running ``curl https://{your domain here}`` - -14. Finally, we suggest editing your config file again to increase your SSL security settings above the default Let's Encrypt. This is the same file from Step 2 above. Edit it to look like the below: - - .. code-block:: text - - upstream backend { - server {ip}:8065; - keepalive 32; - } - - proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=mattermost_cache:10m max_size=3g inactive=120m use_temp_path=off; - - server { - server_name mattermost.example.com; - - location ~ /api/v[0-9]+/(users/)?websocket$ { - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection "upgrade"; - client_max_body_size 50M; - proxy_set_header Host $http_host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header X-Frame-Options SAMEORIGIN; - proxy_buffers 256 16k; - proxy_buffer_size 16k; - client_body_timeout 60s; - send_timeout 300s; - lingering_timeout 5s; - proxy_connect_timeout 90s; - proxy_send_timeout 300s; - proxy_read_timeout 90s; - proxy_http_version 1.1; - proxy_pass http://backend; - } - - location / { - client_max_body_size 50M; - proxy_set_header Connection ""; - proxy_set_header Host $http_host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - proxy_set_header X-Frame-Options SAMEORIGIN; - proxy_buffers 256 16k; - proxy_buffer_size 16k; - proxy_read_timeout 600s; - proxy_http_version 1.1; - proxy_pass http://backend; - } - - listen 443 ssl http2; # managed by Certbot - ssl_certificate /etc/letsencrypt/live/mattermost.example.com/fullchain.pem; # managed by Certbot - ssl_certificate_key /etc/letsencrypt/live/mattermost.example.com/privkey.pem; # managed by Certbot - # include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot - ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot - - ssl_session_timeout 1d; - - # Enable TLS versions (TLSv1.3 is required upcoming HTTP/3 QUIC). - ssl_protocols TLSv1.2 TLSv1.3; - - # Enable TLSv1.3's 0-RTT. Use $ssl_early_data when reverse proxying to - # prevent replay attacks. - # - # @see: https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_early_data - ssl_early_data on; - - ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-SHA; - ssl_prefer_server_ciphers on; - ssl_session_cache shared:SSL:50m; - # HSTS (ngx_http_headers_module is required) (15768000 seconds = six months) - add_header Strict-Transport-Security max-age=15768000; - # OCSP Stapling --- - # fetch OCSP records from URL in ssl_certificate and cache them - ssl_stapling on; - ssl_stapling_verify on; - } - - - server { - if ($host = mattermost.example.com) { - return 301 https://$host$request_uri; - } # managed by Certbot - - - listen 80 default_server; - server_name mattermost.example.com; - return 404; # managed by Certbot - - } - -15. Check that your SSL certificate is set up correctly. - - * Test the SSL certificate by visiting a site such as https://www.ssllabs.com/ssltest/index.html. - * If there’s an error about the missing chain or certificate path, there is likely an intermediate certificate missing that needs to be included. - diff --git a/source/install/faq_kubernetes.rst b/source/install/faq_kubernetes.rst deleted file mode 100644 index 1720ff1d412..00000000000 --- a/source/install/faq_kubernetes.rst +++ /dev/null @@ -1,66 +0,0 @@ -:orphan: -:nosearch: - -What's the difference between the Mattermost Operator and Helm Charts? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The Mattermost Operator is a self-contained set of application/product-specific instructions that runs inside Kubernetes and facilitates application -management and deployment. - -Helm is a tool used to deploy Kubernetes manifests to a cluster, but does not facilitate application management. - -We provide a `helm chart `__ that can be used to to install the Mattermost Operator. - -Does the Mattermost Operator replace the Mattermost Helm Chart? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Although the Mattermost Operator is the recommended deployment option for running Mattermost in Kubernetes, a helm chart for directly deploying Mattermost resources is still available. - -What database and filestore should I use for Mattermost? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Always refer to the Mattermost server documentation for what databases and filestores are supported. - -The following documentation on :doc:`scaling for enterprise ` is a good place to start. - -What are the Operator-Managed database and filestore options? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The Mattermost Operator provides an option to directly provision a database and filestore for a Mattermost installation to use, -but this option is only meant for validation and testing. These options rely on specific releases of operators that we don't maintain. -For production deployments of Mattermost, one of the other database and filestore configuration options should be chosen. - -In particular, the Operator-Managed database option relies on a MySQL operator and MySQL databases are now deprecated in Mattermost. - -Note that you can choose to manage your Mattermost database and filestore in Kubernetes with other operators, but these should -be provisioned separately first and then connected to the Mattermost installation as ``external`` backends. - -Can you use blue-green deployments with different database schemas? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Currently this is not supported as it introduces the possibility of missing a data entry in the database. - -Are environment variables supported? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Yes. However, ``config.json`` file settings will be overridden if the `$MM_SQLSETTINGS_DATASOURCE` environment variable is set. See the :doc:`Environment Variables ` configuration settings documentation for details. - -Issues configuring login with SAML on Kubernetes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -For some SAML authentication configurations, ``502`` status code response can appear during login attempts due to requests being too large. -This can be caused by the default ``proxy-buffer-size`` setting for NGINX Ingress being too low. -To fix this issue, configure an appropriate buffer size (8k or 16k should be sufficient for most cases) with NGINX annotation by adding it to the Mattermost manifest under ``spec.ingressAnnotations``: - -.. code-block:: yaml - - ... - spec: - ... - ingress: - ... - annotations: - nginx.ingress.kubernetes.io/proxy-buffer-size: 16k - ... - -Use caution when changing the buffer size as it may slightly impact NGINX performance. Exact values are machine-dependent. \ No newline at end of file diff --git a/source/install/install-common-intro.rst b/source/install/install-common-intro.rst deleted file mode 100644 index c7c4f2a30c9..00000000000 --- a/source/install/install-common-intro.rst +++ /dev/null @@ -1,13 +0,0 @@ -:orphan: -:nosearch: - -.. This page is intentionally not accessible via the LHS navigation pane because it's common content included on other docs pages. - -A complete Mattermost installation consists of three major components: a proxy server, a database server, and the Mattermost server. You can install all components on one machine, or you can install each component on its own machine. If you have only two machines, then install the proxy and the Mattermost server on one machine, and install the database on the other machine. - -For the database, you can install either PostgreSQL or MySQL. The proxy is NGINX. - -.. note:: - If you have any problems installing Mattermost, see the :doc:`troubleshooting guide `, or `join the Mattermost user community for troubleshooting help `_. - - For help with inviting users to your system, see :doc:`inviting team members ` and other :ref:`getting started information `. \ No newline at end of file diff --git a/source/install/install-debian-mysql.rst b/source/install/install-debian-mysql.rst deleted file mode 100644 index c2e4f8415c3..00000000000 --- a/source/install/install-debian-mysql.rst +++ /dev/null @@ -1,65 +0,0 @@ -:orphan: :nosearch: - -Install MySQL database server ------------------------------ - -Install and set up the database for use by the Mattermost server. You can install either MySQL or PostgreSQL. - -Install MySQL on Debian Buster -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. Log into the server that will host the database, and open a terminal window. - -2. Download the MySQL repository package. - - ``wget https://dev.mysql.com/get/mysql-apt-config_0.8.13-1_all.deb`` - -3. Install the repository - - ``sudo dpkg -i mysql-apt-config*`` - -4. Update your local package list. - - ``sudo apt-get update`` - -5. Add the MySQL repo MySQL. - - ``sudo apt-get install mysql-server`` - - .. note:: - During the install, you'll be prompted to create a password for the MySQL root user. Make a note of the password because you'll need it in the next step. - -6. Log in to MySQL as root. - - ``mysql -u root -p`` - - When prompted, enter the root password that you created when installing MySQL. - -7. Create the Mattermost user 'mmuser'. - - ``mysql> create user 'mmuser'@'%' identified by 'mmuser-password';`` - - .. note:: - 1. Use a password that is more secure than 'mmuser-password'. - 2. The '%' means that mmuser can connect from any machine on the network. However, it's more secure to use the IP address of the machine that hosts Mattermost. For example, if you install Mattermost on the machine with IP address 10.10.10.2, then use the following command: - - ``mysql> create user 'mmuser'@'10.10.10.2' identified by 'mmuser-password';`` - -8. Create the Mattermost database. - - ``mysql> create database mattermost;`` - -9. Grant access privileges to the user 'mmuser'. - - ``mysql> grant all privileges on mattermost.* to 'mmuser'@'%';`` - - .. note:: - This query grants the MySQL user we just created all privileges on the database for convenience. If you need more security you can use this query to grant the user only the privileges necessary to run Mattermost. - - ``mysql> GRANT ALTER, CREATE, DELETE, DROP, INDEX, INSERT, SELECT, UPDATE, REFERENCES ON mattermost.* TO 'mmuser'@'%';`` - -10. Log out of MySQL. - - ``mysql> exit`` - -With the database installed and the initial setup complete, you can now install the Mattermost server. diff --git a/source/install/install-debian-postgresql.rst b/source/install/install-debian-postgresql.rst deleted file mode 100644 index 62660bad113..00000000000 --- a/source/install/install-debian-postgresql.rst +++ /dev/null @@ -1,109 +0,0 @@ -:orphan: :nosearch: - -Install PostgreSQL database server ------------------------------------ - -Install and set up the database for use by the Mattermost server. You can install either PostgreSQL or MySQL. - -Assume that the IP address of this server is 10.10.10.1 - -Install PostgreSQL on Debian Buster -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. Log in to the server that will host the database and issue the following command: - - ``sudo apt-get install postgresql postgresql-contrib`` - - When the installation is complete, the PostgreSQL server is running, and a Linux user account called *postgres* has been created. - -2. Log in to the *postgres* account. - - ``sudo --login --user postgres`` - -3. Start the PostgreSQL interactive terminal. - - ``psql`` - -4. Create the Mattermost database. - - ``postgres=# CREATE DATABASE mattermost;`` - -5. Create the Mattermost user 'mmuser'. - - ``postgres=# CREATE USER mmuser WITH PASSWORD 'mmuser-password';`` - - .. note:: - Use a password that is more secure than 'mmuser-password'. - -6. Grant the user access to the Mattermost database. - - ``postgres=# GRANT ALL PRIVILEGES ON DATABASE mattermost to mmuser;`` - -7. Exit the PostgreSQL interactive terminal. - - ``postgres=# \q`` - -8. Log out of the *postgres* account. - - ``exit`` - -9. (Optional) If you use a different server for your database and the Mattermost app server, you may allow PostgreSQL to listen on all assigned IP Addresses. To do so, open ``/etc/postgresql/9.4/main/postgresql.conf`` as root in a text editor. As a best practice, ensure that only the Mattermost server is able to connect to the PostgreSQL port using a firewall. - - a. Find the following line: - - ``#listen_addresses = 'localhost'`` - - b. Uncomment the line and change ``localhost`` to ``*``: - - ``listen_addresses = '*'`` - - d. Restart PostgreSQL for the change to take effect: - - ``sudo systemctl restart postgresql`` - -10. Modify the file ``pg_hba.conf`` to allow the Mattermost server to communicate with the database. - - **If the Mattermost server and the database are on the same machine**: - - a. Open ``/etc/postgresql/9.4/main/pg_hba.conf`` as root in a text editor. - - b. Find the following lines: - - ``local all all peer`` - - ``host all all ::1/128 ident`` - - c. Change ``peer`` and ``ident`` to ``trust``: - - ``local all all trust`` - - ``host all all ::1/128 trust`` - - **If the Mattermost server and the database are on different machines**: - - a. Open ``/etc/postgresql/9.4/main/pg_hba.conf`` as root in a text editor. - - b. Add the following line to the end of the file, where *{mattermost-server-IP}* is the IP address of the machine that contains the Mattermost server. - - ``host all all {mattermost-server-IP}/32 md5`` - -11. Reload PostgreSQL: - - ``sudo systemctl reload postgresql`` - -12. Verify that you can connect with the user *mmuser*. - - a. If the Mattermost server and the database are on the same machine, use the following command: - - ``psql --dbname=mattermost --username=mmuser --password`` - - b. If the Mattermost server is on a different machine, log into that machine and use the following command: - - ``psql --host={postgres-server-IP} --dbname=mattermost --username=mmuser --password`` - - .. note:: - You might have to install the PostgreSQL client software to use the command. - - The PostgreSQL interactive terminal starts. To exit the PostgreSQL interactive terminal, type ``\q`` and press **Enter**. - -With the database installed and the initial setup complete, you can now install the Mattermost server. diff --git a/source/install/install-debian-server.rst b/source/install/install-debian-server.rst deleted file mode 100644 index bf4c94d600c..00000000000 --- a/source/install/install-debian-server.rst +++ /dev/null @@ -1,24 +0,0 @@ -:orphan: :nosearch: - -.. This page is intentionally not accessible via the LHS navigation pane because it's common content included on other docs pages. - -Install Debian Buster ----------------------- - -Install the 64-bit version of Debian on each machine that hosts one or more of the components. - -**To install Debian Buster:** - -1. To install Debian Buster, see `Debian Installation documentation `__ for details. - -2. After the system is installed, make sure that it's up to date with the most recent security patches. Open a terminal window and issue the following commands as root: - - ``apt-get update`` - - ``apt-get upgrade`` - -3. Install *sudo* and *curl* for use later in the installation: ``apt-get install sudo curl gnupg``. - -4. Add your username to the sudo group. In the following command, replace {username} with your own username: ``usermod -a -G sudo {username}``. - -Now that the system is up to date and your user is in the sudo group, you can start installing the components that make up a Mattermost system. diff --git a/source/install/install-debian.rst b/source/install/install-debian.rst deleted file mode 100644 index e25c45e2bb8..00000000000 --- a/source/install/install-debian.rst +++ /dev/null @@ -1,145 +0,0 @@ -:orphan: - -Installing Mattermost on Debian Buster -======================================= - -.. include:: ../_static/badges/allplans-selfhosted.rst - :start-after: :nosearch: - -Install a production-ready Mattermost system on up to three machines. - -.. include:: install-common-intro.rst - :start-after: :nosearch: - -.. include:: install-tar.rst - -Install a database ------------------- - -.. note:: - - You only need one database: either PostgreSQL or MySQL. See the :ref:`database software ` documentation for details on database version support. - -.. tab:: Install PostgreSQL - - Install and set up a PostgreSQL database for use by the Mattermost server. These instructions assume that the IP address of this server is ``10.10.10.1``. - - 1. Log in to the server that will host the database, and install PostgreSQL. See the `PostgreSQL `_ documentation for details. When the installation is complete, the PostgreSQL server is running, and a Linux user account called *postgres* has been created. - - 2. Log in to the *postgres* account by running ``sudo --login --user postgres``. - - 3. Start the PostgreSQL interactive terminal by running ``psql``. - - 4. Create the Mattermost database by running ``postgres=# CREATE DATABASE mattermost;``. - - 5. Create the Mattermost user 'mmuser' by running ``postgres=# CREATE USER mmuser WITH PASSWORD 'mmuser-password';``. - - .. note:: - - Use a password that is more secure than ``mmuser-password``. - - 6. Grant the user access to the Mattermost database by running ``postgres=# GRANT ALL PRIVILEGES ON DATABASE mattermost to mmuser;``. - - 7. Exit the PostgreSQL interactive terminal by running ``postgres=# \q``. - - 8. Log out of the *postgres* account by running ``exit``. - - 9. (Optional) If you use separate servers for your database and the Mattermost app server, you may allow PostgreSQL to listen on all assigned IP Addresses. To do so, open ``/etc/postgresql/{version}/main/postgresql.conf`` as *root* in a text editor, and replacing ``{version}`` with the version of PostgreSQL that's currently running. As a best practice, ensure that only the Mattermost server is able to connect to the PostgreSQL port using a firewall. - - a. Find the following line: ``#listen_addresses = 'localhost'``. - - b. Uncomment the line and change ``localhost`` to ``*``: ``listen_addresses = '*'``. - - c. Restart PostgreSQL for the change to take effect: ``sudo systemctl restart postgresql``. - - 10. Modify the file ``pg_hba.conf`` to allow the Mattermost server to communicate with the database. - - **If the Mattermost server and the database are on the same machine**: - - a. Open ``/etc/postgresql/9.4/main/pg_hba.conf`` in a text editor as *root* user. - - b. Find the following lines: - - ``local all all peer`` - - ``host all all ::1/128 ident`` - - c. Change ``peer`` and ``ident`` to ``trust``: - - ``local all all trust`` - - ``host all all ::1/128 trust`` - - **If the Mattermost server and the database are on different machines**: - - a. Open ``/etc/postgresql/9.4/main/pg_hba.conf`` in a text editor as *root* user. - - b. Add the following line to the end of the file, where ``{mattermost-server-IP}`` is the IP address of the machine that contains the Mattermost server: ``host all all {mattermost-server-IP}/32 md5``. - - 11. Reload PostgreSQL by running ``sudo systemctl reload postgresql``. - - 12. Verify that you can connect with the user *mmuser*. - - a. If the Mattermost server and the database are on the same machine, use the following command: ``psql --dbname=mattermost --username=mmuser --password`` - - b. If the Mattermost server is on a different machine, log into that machine and use the following command: ``psql --host={postgres-server-IP} --dbname=mattermost --username=mmuser --password`` - - .. note:: - - You might have to install the PostgreSQL client software to use the command. - - The PostgreSQL interactive terminal starts. To exit the PostgreSQL interactive terminal, type ``\q`` and press :kbd:`Enter` on Windows or Linux, or :kbd:`↵` on Mac. - - With the database installed and the initial setup complete, you can now install the Mattermost server. - -.. tab:: Install MySQL - - Install and set up a MySQL database for use by the Mattermost server. - - 1. Log into the server that will host the database, and open a terminal window. - - 2. Download the MySQL repository package by running ``wget https://dev.mysql.com/get/mysql-apt-config_0.8.13-1_all.deb``. - - 3. Install the repository by running ``sudo dpkg -i mysql-apt-config*``. - - 4. Update your local package list by running ``sudo apt-get update``. - - 5. Add the MySQL repo MySQL by running ``sudo apt-get install mysql-server``. - - .. note:: - - During the install, you'll be prompted to create a password for the MySQL root user. Make a note of the password because you'll need it in the next step. - - 6. Log in to MySQL as *root* by running ``mysql -u root -p``. When prompted, enter the root password that you created when installing MySQL. - - 7. Create the Mattermost user ``mmuser`` by running ``mysql> create user 'mmuser'@'%' identified by 'mmuser-password';``. - - .. note:: - - - Use a password that is more secure than ``mmuser-password``. - - The ``%`` means that mmuser can connect from any machine on the network. However, it's more secure to use the IP address of the machine that hosts Mattermost. For example, if you install Mattermost on the machine with IP address 10.10.10.2, then use the following command: ``mysql> create user 'mmuser'@'10.10.10.2' identified by 'mmuser-password';``. - - 8. Create the Mattermost database by running ``mysql> create database mattermost;``. - - 9. Grant access privileges to the user ``mmuser`` by running ``mysql> grant all privileges on mattermost.* to 'mmuser'@'%';``. - - .. note:: - - This query grants the MySQL user we just created all privileges on the database for convenience. If you need more security, you can use the following query to grant the user only the privileges necessary to run Mattermost: ``mysql> GRANT ALTER, CREATE, DELETE, DROP, INDEX, INSERT, SELECT, UPDATE, REFERENCES ON mattermost.* TO 'mmuser'@'%';``. - - 10. Log out of MySQL by running ``mysql> exit``. Once the database is installed, and the initial setup is complete, you can install the Mattermost server. - -.. include:: config-mattermost-server.rst - :start-after: :nosearch: - -.. include:: config-tls-mattermost.rst - :start-after: :nosearch: - -.. include:: install-nginx.rst - :start-after: :nosearch: - -.. include:: config-proxy-nginx.rst - :start-after: :nosearch: - -.. include:: config-ssl-http2-nginx.rst - :start-after: :nosearch: \ No newline at end of file diff --git a/source/install/install-docker.rst b/source/install/install-docker.rst index 5dddbd82fde..c2e7fda9b1b 100644 --- a/source/install/install-docker.rst +++ b/source/install/install-docker.rst @@ -41,8 +41,114 @@ If you don't have Docker installed, follow the instructions below based on your Deploy Mattermost on Docker for production use ---------------------------------------------- -.. include:: common-prod-deploy-docker.rst - :start-after: :nosearch: +You'll need `Docker Engine `__ and `Docker Compose `__ (release 1.28 or later). + +.. important:: + + - The production configuration results in two separate containers: one for the database and one for the application. An optional third container results when using NGINX for reverse proxy. + - Encountering issues with your Docker deployment? See the :ref:`Docker deployment troubleshooting ` documentation for details. + +To deploy Mattermost on Docker: + +1. In a terminal window, clone the repository and enter the directory. + + .. code-block:: sh + + git clone https://github.com/mattermost/docker + cd docker + +2. Create your ``.env`` file by copying and adjusting the ``env.example`` file. + + .. code-block:: sh + + cp env.example .env + +.. important:: + + At a minimum, you must edit the ``DOMAIN`` value in the ``.env`` file to correspond to the domain for your Mattermost server. + +3. Create the required directories and set their permissions. + + .. code-block:: sh + + mkdir -p ./volumes/app/mattermost/{config,data,logs,plugins,client/plugins,bleve-indexes} + sudo chown -R 2000:2000 ./volumes/app/mattermost + +4. Configure TLS for NGINX *(optional)*. If you're not using the included NGINX reverse proxy, you can skip this step. + + **If creating a new certificate and key:** + + .. code-block:: sh + + bash scripts/issue-certificate.sh -d -o ${PWD}/certs + + To include the certificate and key, uncomment the following lines in your ``.env`` file and ensure they point to the appropriate files. + + .. code-block:: sh + + #CERT_PATH=./certs/etc/letsencrypt/live/${DOMAIN}/fullchain.pem + #KEY_PATH=./certs/etc/letsencrypt/live/${DOMAIN}/privkey.pem + + **If using a pre-existing certificate and key:** + + .. code-block:: sh + + mkdir -p ./volumes/web/cert + cp .pem ./volumes/web/cert/cert.pem + cp .pem ./volumes/web/cert/key-no-password.pem + + To include the certificate and key, ensure the following lines in your ``.env`` file points to the appropriate files. + + .. code-block:: sh + + CERT_PATH=./volumes/web/cert/cert.pem + KEY_PATH=./volumes/web/cert/key-no-password.pem + +5. Configure SSO with GitLab *(optional)*. If you want to use SSO with GitLab, and you're using a self-signed certificate, you have to add the PKI chain for your authority. This is required to avoid the ``Token request failed: certificate signed by unknown authority`` error. + + To add the PKI chain, uncomment this line in your ``.env`` file, and ensure it points to your ``pki_chain.pem`` file: + + .. code-block:: sh + + #GITLAB_PKI_CHAIN_PATH=/pki_chain.pem + + Then uncomment this line in your ``docker-compose.yml`` file, and ensure it points to the same ``pki_chain.pem`` file: + + .. code-block:: sh + + # - ${GITLAB_PKI_CHAIN_PATH}:/etc/ssl/certs/pki_chain.pem:ro + +6. Deploy Mattermost. + + **Without using the included NGINX:** + + .. code-block:: sh + + sudo docker compose -f docker-compose.yml -f docker-compose.without-nginx.yml up -d + + To access your new Mattermost deployment, navigate to ``http://:8065/`` in your browser. + + To shut down your deployment: + + .. code-block:: sh + + sudo docker compose -f docker-compose.yml -f docker-compose.without-nginx.yml down + + **Using the included NGINX:** + + .. code-block:: sh + + sudo docker compose -f docker-compose.yml -f docker-compose.nginx.yml up -d + + To access your new Mattermost deployment via HTTPS, navigate to ``https:///`` in your browser. + + To shut down your deployment: + + .. code-block:: sh + + sudo docker compose -f docker-compose.yml -f docker-compose.nginx.yml down + +7. Create your first Mattermost system admin user, :doc:`invite more users `, and explore the Mattermost platform. Upgrade from ``mattermost-docker`` ----------------------------------- diff --git a/source/install/install-kubernetes.rst b/source/install/install-kubernetes.rst index 1aabbebd278..e28444ecadf 100644 --- a/source/install/install-kubernetes.rst +++ b/source/install/install-kubernetes.rst @@ -378,5 +378,66 @@ Check out this `YouTube sneak peek demo `__, by Ni Frequently asked questions -------------------------- -.. include:: faq_kubernetes.rst - :start-after: :nosearch: \ No newline at end of file +What's the difference between the Mattermost Operator and Helm Charts? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Mattermost Operator is a self-contained set of application/product-specific instructions that runs inside Kubernetes and facilitates application +management and deployment. + +Helm is a tool used to deploy Kubernetes manifests to a cluster, but does not facilitate application management. + +We provide a `helm chart `__ that can be used to to install the Mattermost Operator. + +Does the Mattermost Operator replace the Mattermost Helm Chart? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Although the Mattermost Operator is the recommended deployment option for running Mattermost in Kubernetes, a helm chart for directly deploying Mattermost resources is still available. + +What database and filestore should I use for Mattermost? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Always refer to the Mattermost server documentation for what databases and filestores are supported. + +The following documentation on :doc:`scaling for enterprise ` is a good place to start. + +What are the Operator-Managed database and filestore options? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Mattermost Operator provides an option to directly provision a database and filestore for a Mattermost installation to use, +but this option is only meant for validation and testing. These options rely on specific releases of operators that we don't maintain. +For production deployments of Mattermost, one of the other database and filestore configuration options should be chosen. + +In particular, the Operator-Managed database option relies on a MySQL operator and MySQL databases are now deprecated in Mattermost. + +Note that you can choose to manage your Mattermost database and filestore in Kubernetes with other operators, but these should +be provisioned separately first and then connected to the Mattermost installation as ``external`` backends. + +Can you use blue-green deployments with different database schemas? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Currently this is not supported as it introduces the possibility of missing a data entry in the database. + +Are environment variables supported? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Yes. However, ``config.json`` file settings will be overridden if the `$MM_SQLSETTINGS_DATASOURCE` environment variable is set. See the :doc:`Environment Variables ` configuration settings documentation for details. + +Issues configuring login with SAML on Kubernetes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For some SAML authentication configurations, ``502`` status code response can appear during login attempts due to requests being too large. +This can be caused by the default ``proxy-buffer-size`` setting for NGINX Ingress being too low. +To fix this issue, configure an appropriate buffer size (8k or 16k should be sufficient for most cases) with NGINX annotation by adding it to the Mattermost manifest under ``spec.ingressAnnotations``: + +.. code-block:: yaml + + ... + spec: + ... + ingress: + ... + annotations: + nginx.ingress.kubernetes.io/proxy-buffer-size: 16k + ... + +Use caution when changing the buffer size as it may slightly impact NGINX performance. Exact values are machine-dependent. \ No newline at end of file diff --git a/source/install/install-nginx.rst b/source/install/install-nginx.rst deleted file mode 100644 index 94359a610c5..00000000000 --- a/source/install/install-nginx.rst +++ /dev/null @@ -1,79 +0,0 @@ -:nosearch: - -.. This page is intentionally not accessible via the LHS navigation pane because it's common content included on other docs pages. - -Install NGINX server --------------------- - -NGINX is a popular web server and is responsible for hosting some of the largest and highest-traffic sites on the internet. It's more resource-friendly than Apache in most cases, and can be used as a web server or reverse proxy. - -In a production setting, we recommend using a proxy server for greater security and performance of Mattermost. - -- SSL termination -- HTTP to HTTPS redirect -- Port mapping ``:80`` to ``:8065`` -- Standard request logs - -Install NGINX on Ubuntu Server -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. Log in to the server that will host the proxy and open a terminal window. - -2. Install NGINX. - - Because NGINX is available in Ubuntu's default repositories, it's possible to install it from these repositories using the ``apt`` packaging system. First, update your local ``apt`` package index for access to the most recent package listings. Then, install ``nginx``: - - - .. code-block:: sh - - sudo apt update - sudo apt install nginx - - After accepting the procedure, ``apt`` will install NGINX and any required dependencies to your server. - -3. After installing it, you already have everything you need. You can point your browser to your server IP address. You should see the default NGINX landing page: - - .. image:: /images/install_nginx_welcome.png - :alt: Example of the default NGINX landing page. - - If you see this page, you've successfully installed NGINX on your web server. This page is included with NGINX to show you that the server is running correctly. - - Or you can also verify it by running ``curl http://localhost``. - - If NGINX is running, you see the following output: - - .. code-block:: html - - - - - Welcome to nginx! - . - . - . -

Thank you for using nginx.

- - - -Manage the NGINX process -~~~~~~~~~~~~~~~~~~~~~~~~ - -Now that you have your web server up and running, let's review some basic management commands. These are all run in the command line interface. - -To stop your web server, use: ``sudo systemctl stop nginx`` - -To start the web server when it's stopped, use: ``sudo systemctl start nginx`` - -To stop and then start the service again, use: ``sudo systemctl restart nginx`` - -If you're simply making configuration changes, NGINX can often reload without dropping connections. To do this, use: ``sudo systemctl reload nginx`` - -By default, NGINX is configured to start automatically when the server boots. If this isn't what you want, you can disable this behavior using: ``sudo systemctl disable nginx`` - -To re-enable the service to start up at boot, use: ``sudo systemctl enable nginx`` - -What to do next -~~~~~~~~~~~~~~~ - -1. Map a fully qualified domain name (FQDN) such as ``mattermost.example.com`` on your DNS server/service, to point to the NGINX server. -2. Configure NGINX to proxy connections from the internet to the Mattermost server. diff --git a/source/install/install-rhel-nginx.rst b/source/install/install-rhel-nginx.rst deleted file mode 100644 index 18fadde27a4..00000000000 --- a/source/install/install-rhel-nginx.rst +++ /dev/null @@ -1,58 +0,0 @@ -:orphan: :nosearch: - -.. This page is intentionally not accessible via the LHS navigation pane because it's common content included on other docs pages. - -Install NGINX server ---------------------- - -In a production setting, use a proxy server for greater security and performance of Mattermost: - - - SSL termination - - HTTP to HTTPS redirect - - Port mapping ``:80`` to ``:8065`` - - Standard request logs - -1. Log in to the server that will host the proxy, and open a terminal window. - -2. Create the file ``/etc/yum.repos.d/nginx.repo`` by running ``sudo touch /etc/yum.repos.d/nginx.repo``. - - If you are on RHEL 8 you can skip to **Step 4. Install NGINX**. - -3. Open the file as *root* in a text editor and add the following contents, where *{version}* is **7** for RHEL 7: - - .. code-block:: text - - [nginx] - name=nginx repo - baseurl=https://nginx.org/packages/rhel/{version}/$basearch/ - gpgcheck=0 - enabled=1 - -4. Install NGINX by running ``sudo yum install nginx.x86_64``. - -5. After the installation is complete, start NGINX by running ``sudo systemctl start nginx``. - On RHEL 6: - -6. **Optional** Set NGINX to start at system boot by running ``sudo systemctl enable nginx``. - -7. Verify that NGINX is running by running ``curl http://localhost``. - - If NGINX is running, you see the following output: - - .. code-block:: html - - - - - Welcome to nginx! - . - . - . -

Thank you for using nginx.

- - - -**What to do next** - -1. Map a fully qualified domain name (FQDN) such as ``mattermost.example.com`` on your DNS server/service, to point to the NGINX server. -2. Configure NGINX to proxy connections from the Internet to the Mattermost Server. diff --git a/source/install/setup-mattermost-server.rst b/source/install/setup-mattermost-server.rst index 8567ca8866b..d830ae5e4df 100644 --- a/source/install/setup-mattermost-server.rst +++ b/source/install/setup-mattermost-server.rst @@ -1,6 +1,8 @@ :orphan: :nosearch: +.. This page is intentionally not accessible via the LHS navigation pane because it's common content included on other docs pages. + Before you start the Mattermost Server, you need to edit the configuration file. A default configuration file is located at ``/opt/mattermost/config/config.json``. We recommend taking a backup of this default config ahead of making changes: diff --git a/source/install/setup-nginx-proxy.rst b/source/install/setup-nginx-proxy.rst index 1275f56fc75..41b6a7ab225 100644 --- a/source/install/setup-nginx-proxy.rst +++ b/source/install/setup-nginx-proxy.rst @@ -4,14 +4,404 @@ Set up an NGINX proxy .. include:: ../_static/badges/allplans-selfhosted.rst :start-after: :nosearch: -.. include:: install-nginx.rst - :start-after: :nosearch: +Install NGINX server +-------------------- -.. include:: config-proxy-nginx.rst - :start-after: :nosearch: +NGINX is a popular web server and is responsible for hosting some of the largest and highest-traffic sites on the internet. It's more resource-friendly than Apache in most cases, and can be used as a web server or reverse proxy. -.. include:: config-ssl-http2-nginx.rst - :start-after: :nosearch: +In a production setting, we recommend using a proxy server for greater security and performance of Mattermost. + +- SSL termination +- HTTP to HTTPS redirect +- Port mapping ``:80`` to ``:8065`` +- Standard request logs + +Install NGINX on Ubuntu Server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Log in to the server that will host the proxy and open a terminal window. + +2. Install NGINX. + + Because NGINX is available in Ubuntu's default repositories, it's possible to install it from these repositories using the ``apt`` packaging system. First, update your local ``apt`` package index for access to the most recent package listings. Then, install ``nginx``: + + + .. code-block:: sh + + sudo apt update + sudo apt install nginx + + After accepting the procedure, ``apt`` will install NGINX and any required dependencies to your server. + +3. After installing it, you already have everything you need. You can point your browser to your server IP address. You should see the default NGINX landing page: + + .. image:: /images/install_nginx_welcome.png + :alt: Example of the default NGINX landing page. + + If you see this page, you've successfully installed NGINX on your web server. This page is included with NGINX to show you that the server is running correctly. + + Or you can also verify it by running ``curl http://localhost``. + + If NGINX is running, you see the following output: + + .. code-block:: html + + + + + Welcome to nginx! + . + . + . +

Thank you for using nginx.

+ + + +Manage the NGINX process +~~~~~~~~~~~~~~~~~~~~~~~~ + +Now that you have your web server up and running, let's review some basic management commands. These are all run in the command line interface. + +To stop your web server, use: ``sudo systemctl stop nginx`` + +To start the web server when it's stopped, use: ``sudo systemctl start nginx`` + +To stop and then start the service again, use: ``sudo systemctl restart nginx`` + +If you're simply making configuration changes, NGINX can often reload without dropping connections. To do this, use: ``sudo systemctl reload nginx`` + +By default, NGINX is configured to start automatically when the server boots. If this isn't what you want, you can disable this behavior using: ``sudo systemctl disable nginx`` + +To re-enable the service to start up at boot, use: ``sudo systemctl enable nginx`` + +What to do next +~~~~~~~~~~~~~~~ + +1. Map a fully qualified domain name (FQDN) such as ``mattermost.example.com`` on your DNS server/service, to point to the NGINX server. +2. Configure NGINX to proxy connections from the internet to the Mattermost server. + +Configure NGINX as a proxy for Mattermost server +------------------------------------------------ + +NGINX is configured using a file in the ``/etc/nginx/sites-available`` directory. You need to create the file and then enable it. When creating the file, you need the IP address of your Mattermost server and the fully qualified domain name (FQDN) of your Mattermost website. + +1. Log in to the server that hosts NGINX and open a terminal window. +2. Create a configuration file for Mattermost by running the following command: + + ``sudo touch /etc/nginx/sites-available/mattermost`` on Ubuntu + ``sudo touch /etc/nginx/conf.d/mattermost`` on RHEL 8 + +3. Open the file ``/etc/nginx/sites-available/mattermost`` (Ubuntu) or ``/etc/nginx/conf.d/mattermost`` (RHEL 8) as *root* user in a text editor and replace its contents, if any, with the following lines. Make sure that you use your own values for the Mattermost server IP address and FQDN for *server_name*. + +SSL and HTTP/2 with server push are enabled in the provided configuration example. + + .. note:: + + - If you're going to use Let's Encrypt to manage your SSL certificate, stop at step 3 and see the :ref:`NGINX HTTP/2 and SSL product documentation ` for details. + - You'll need valid SSL certificates in order for NGINX to pin the certificates properly. Additionally, your browser must have permissions to accept the certificate as a valid CA-signed certificate. + - Note that the IP address included in the examples in this documentation may not match your network configuration. + - If you're running NGINX on the same machine as Mattermost, and NGINX resolves ``localhost`` to more than one IP address (IPv4 or IPv6), we recommend using ``127.0.0.1`` instead of ``localhost``. + + .. code-block:: text + + upstream backend { + server 10.10.10.2:8065; + keepalive 32; + } + + server { + listen 80 default_server; + server_name mattermost.example.com; + return 301 https://$server_name$request_uri; + } + + server { + listen 443 ssl http2; + listen [::]:443 ssl http2; + server_name mattermost.example.com; + + http2_push_preload on; # Enable HTTP/2 Server Push + + ssl_certificate /etc/letsencrypt/live/{domain-name}/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/{domain-name}/privkey.pem; + ssl_session_timeout 1d; + + # Enable TLS versions (TLSv1.3 is required upcoming HTTP/3 QUIC). + ssl_protocols TLSv1.2 TLSv1.3; + + # Enable TLSv1.3's 0-RTT. Use $ssl_early_data when reverse proxying to + # prevent replay attacks. + # + # @see: https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_early_data + ssl_early_data on; + + ssl_ciphers 'ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384'; + ssl_prefer_server_ciphers on; + ssl_session_cache shared:SSL:50m; + # HSTS (ngx_http_headers_module is required) (15768000 seconds = six months) + add_header Strict-Transport-Security max-age=15768000; + # OCSP Stapling --- + # fetch OCSP records from URL in ssl_certificate and cache them + ssl_stapling on; + ssl_stapling_verify on; + + add_header X-Early-Data $tls1_3_early_data; + + location ~ /api/v[0-9]+/(users/)?websocket$ { + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + client_max_body_size 50M; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Frame-Options SAMEORIGIN; + proxy_buffers 256 16k; + proxy_buffer_size 16k; + client_body_timeout 60s; + send_timeout 300s; + lingering_timeout 5s; + proxy_connect_timeout 90s; + proxy_send_timeout 300s; + proxy_read_timeout 90s; + proxy_http_version 1.1; + proxy_pass http://backend; + } + + location / { + client_max_body_size 100M; + proxy_set_header Connection ""; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Frame-Options SAMEORIGIN; + proxy_buffers 256 16k; + proxy_buffer_size 16k; + proxy_read_timeout 600s; + proxy_http_version 1.1; + proxy_pass http://backend; + } + } + + # This block is useful for debugging TLS v1.3. Please feel free to remove this + # and use the `$ssl_early_data` variable exposed by NGINX directly should you + # wish to do so. + map $ssl_early_data $tls1_3_early_data { + "~." $ssl_early_data; + default ""; + } + +4. Remove the existing default sites-enabled file by running ``sudo rm /etc/nginx/sites-enabled/default`` (Ubuntu) or ``sudo rm /etc/nginx/conf.d/default`` (RHEL 8) + +5. Enable the mattermost configuration by running ``sudo ln -s /etc/nginx/sites-available/mattermost /etc/nginx/sites-enabled/mattermost`` (Ubuntu) or ``sudo ln -s /etc/nginx/conf.d/mattermost /etc/nginx/conf.d/default.conf`` (RHEL 8) + +6. Restart NGINX by running ``sudo systemctl restart nginx``. + +7. Verify that you can see Mattermost through the proxy by running ``curl https://localhost``. + + If everything is working, you will see the HTML for the Mattermost signup page. + +8. Restrict access to port 8065. + + By default, the Mattermost server accepts connections on port 8065 from every machine on the network. Use your firewall to deny connections on port 8065 to all machines except the machine that hosts NGINX and the machine that you use to administer the Mattermost server. If you're installing on Amazon Web Services, you can use Security Groups to restrict access. + +Now that NGINX is installed and running, you can configure it to use SSL, which allows you to use HTTPS connections and the HTTP/2 protocol. + +Configure NGINX with SSL and HTTP/2 +----------------------------------- + +NGINX is configured using a file in the ``/etc/nginx/sites-available`` directory. You need to create the file and then enable it. When creating the file, you need the IP address of your Mattermost server and the fully qualified domain name (FQDN) of your Mattermost website. + +Using SSL gives greater security by ensuring that communications between Mattermost clients and the Mattermost server are encrypted. It also allows you to configure NGINX to use the HTTP/2 protocol. + +Although you can configure HTTP/2 without SSL, both Firefox and Chrome browsers support HTTP/2 on secure connections only. + +You can use any certificate that you want, but these instructions show you how to download and install certificates from `Let's Encrypt `__, a free certificate authority. + +.. note:: + + If Let’s Encrypt is enabled, forward port 80 through a firewall, with :ref:`Forward80To443 ` ``config.json`` setting set to ``true`` to complete the Let’s Encrypt certification. See the `Let's Encrypt/Certbot documentation `_ for additional assistance. + +1. Log in to the server that hosts NGINX and open a terminal window. + +2. Open the your Mattermost ``nginx.conf`` file as *root* in a text editor, then update the ``{ip}`` address in the ``upstream backend`` to point towards Mattermost (such as ``127.0.0.1:8065``), and update the ``server_name`` to be your domain for Mattermost. + + .. note:: + + - On Ubuntu this file is located at ``/etc/nginx/sites-available/``. If you don't have this file, run ``sudo touch /etc/nginx/sites-available/mattermost``. + - On CentOS/RHEL this file is located at ``/etc/nginx/conf.d/``. If you don't have this file, run ``sudo touch /etc/nginx/conf.d/mattermost``. + - The IP address included in the examples in this documentation may not match your network configuration. + - If you're running NGINX on the same machine as Mattermost, and NGINX resolves ``localhost`` to more than one IP address (IPv4 or IPv6), we recommend using ``127.0.0.1`` instead of ``localhost``. + + .. code-block:: text + + upstream backend { + server {ip}:8065; + keepalive 32; + } + + server { + listen 80 default_server; + server_name mattermost.example.com; + + location ~ /api/v[0-9]+/(users/)?websocket$ { + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + client_max_body_size 50M; + proxy_set_header Host $http_host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Frame-Options SAMEORIGIN; + proxy_buffers 256 16k; + proxy_buffer_size 16k; + client_body_timeout 60s; + send_timeout 300s; + lingering_timeout 5s; + proxy_connect_timeout 90s; + proxy_send_timeout 300s; + proxy_read_timeout 90s; + proxy_pass http://backend; + } + + location / { + client_max_body_size 50M; + proxy_set_header Connection ""; + proxy_set_header Host $http_host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Frame-Options SAMEORIGIN; + proxy_buffers 256 16k; + proxy_buffer_size 16k; + proxy_read_timeout 600s; + proxy_http_version 1.1; + proxy_pass http://backend; + } + } + +3. Remove the existing default sites-enabled file by running ``sudo rm /etc/nginx/sites-enabled/default`` (Ubuntu) or ``sudo rm /etc/nginx/conf.d/default`` (RHEL 8). + +4. Enable the Mattermost configuration by running ``sudo ln -s /etc/nginx/sites-available/mattermost /etc/nginx/sites-enabled/mattermost`` (Ubuntu) or ``sudo ln -s /etc/nginx/conf.d/mattermost /etc/nginx/conf.d/default.conf`` (RHEL 8). + +5. Run ``sudo nginx -t`` to ensure your configuration is done properly. If you get an error, look into the NGINX config and make the needed changes to the file under ``/etc/nginx/sites-available/mattermost``. + +6. Restart NGINX by running ``sudo systemctl start nginx``. + +7. Verify that you can see Mattermost through the proxy by running ``curl http://localhost``. + + If everything is working, you will see the HTML for the Mattermost signup page. You will see invalid certificate when accessing through the IP or localhost. Use the full FQDN domain to verify if the SSL certificate has pinned properly and is valid. + +8. Install and update Snap by running ``sudo snap install core; sudo snap refresh core``. + +9. Install the Certbot package by running ``sudo snap install --classic certbot``. + +10. Add a symbolic link to ensure Certbot can run by running ``sudo ln -s /snap/bin/certbot /usr/bin/certbot``. + +11. Run the Let's Encrypt installer dry-run to ensure your DNS is configured properly by running ``sudo certbot certonly --dry-run``. + + This will prompt you to enter your email, accept the TOS, share your email, and select the domain you're activating certbot for. This will validate that your DNS points to this server properly and you are able to successfully generate a certificate. If this finishes successfully, proceed to step 12. + +12. Run the Let's Encrypt installer by running ``sudo certbot``. This will run certbot and will automatically edit your NGINX config file for the site(s) selected. + +13. Ensure your SSL is configured properly by running ``curl https://{your domain here}`` + +14. Finally, we suggest editing your config file again to increase your SSL security settings above the default Let's Encrypt. This is the same file from Step 2 above. Edit it to look like the below: + + .. code-block:: text + + upstream backend { + server {ip}:8065; + keepalive 32; + } + + proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=mattermost_cache:10m max_size=3g inactive=120m use_temp_path=off; + + server { + server_name mattermost.example.com; + + location ~ /api/v[0-9]+/(users/)?websocket$ { + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + client_max_body_size 50M; + proxy_set_header Host $http_host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Frame-Options SAMEORIGIN; + proxy_buffers 256 16k; + proxy_buffer_size 16k; + client_body_timeout 60s; + send_timeout 300s; + lingering_timeout 5s; + proxy_connect_timeout 90s; + proxy_send_timeout 300s; + proxy_read_timeout 90s; + proxy_http_version 1.1; + proxy_pass http://backend; + } + + location / { + client_max_body_size 50M; + proxy_set_header Connection ""; + proxy_set_header Host $http_host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Frame-Options SAMEORIGIN; + proxy_buffers 256 16k; + proxy_buffer_size 16k; + proxy_read_timeout 600s; + proxy_http_version 1.1; + proxy_pass http://backend; + } + + listen 443 ssl http2; # managed by Certbot + ssl_certificate /etc/letsencrypt/live/mattermost.example.com/fullchain.pem; # managed by Certbot + ssl_certificate_key /etc/letsencrypt/live/mattermost.example.com/privkey.pem; # managed by Certbot + # include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot + ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot + + ssl_session_timeout 1d; + + # Enable TLS versions (TLSv1.3 is required upcoming HTTP/3 QUIC). + ssl_protocols TLSv1.2 TLSv1.3; + + # Enable TLSv1.3's 0-RTT. Use $ssl_early_data when reverse proxying to + # prevent replay attacks. + # + # @see: https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_early_data + ssl_early_data on; + + ssl_ciphers ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-SHA; + ssl_prefer_server_ciphers on; + ssl_session_cache shared:SSL:50m; + # HSTS (ngx_http_headers_module is required) (15768000 seconds = six months) + add_header Strict-Transport-Security max-age=15768000; + # OCSP Stapling --- + # fetch OCSP records from URL in ssl_certificate and cache them + ssl_stapling on; + ssl_stapling_verify on; + } + + + server { + if ($host = mattermost.example.com) { + return 301 https://$host$request_uri; + } # managed by Certbot + + + listen 80 default_server; + server_name mattermost.example.com; + return 404; # managed by Certbot + + } + +15. Check that your SSL certificate is set up correctly. + + * Test the SSL certificate by visiting a site such as https://www.ssllabs.com/ssltest/index.html. + * If there’s an error about the missing chain or certificate path, there is likely an intermediate certificate missing that needs to be included. NGINX configuration FAQ ----------------------- diff --git a/source/install/trial-mattermost-using-docker.rst b/source/install/trial-mattermost-using-docker.rst index 81f78256e2b..da051a3a764 100644 --- a/source/install/trial-mattermost-using-docker.rst +++ b/source/install/trial-mattermost-using-docker.rst @@ -10,8 +10,30 @@ Trial Mattermost using Docker .. _Preview Mattermost on Docker: -.. include:: common-local-deploy-docker.rst - :start-after: :nosearch: +Preview Mattermost using Docker +------------------------------- + +Using the `Mattermost Docker Preview Image `__ is the fastest way to trial Mattermost in **Preview Mode**, and explore product functionality on a single local machine. + +.. important:: + + This local image is self-contained (i.e., it has an internal database and works out of the box). Dropping a container using this image removes data and configuration as expected. You can see the :doc:`configuration settings ` documentation to learn more about customizing your trial deployment. + + **Preview Mode** shouldn't be used in a production environment, as it uses a known password string, contains other non-production configuration settings, has email disabled, keeps no persistent data (all data lives inside the container), and doesn't support upgrades. + + If you are planning to use the calling functionality in **Preview Mode** on a non-local environment, you should ensure that the server is running on a secure (HTTPs) connection and that the :ref:`network requirements ` to run calls are met. + +1. Install `Docker `__. + +2. Once you have Docker, run the following command in a terminal window: + + .. code-block:: sh + + docker run --name mattermost-preview -d --publish 8065:8065 --publish 8443:8443 mattermost/mattermost-preview + +3. When Docker is done fetching the image, navigate to ``http://localhost:8065/`` in your browser to preview Mattermost. +4. Select **Don't have an account** in the top right corner of the screen to create an account for your preview instance. If you don't see this option, ensure that the :ref:`Enable open server ` configuration setting is enabled. This setting is disabled for self-hosted Mattermost deployments by default. +5. Log in to your preview instance with your user credentials. Troubleshooting your preview deployment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/manage/bulk-export-data.rst b/source/manage/bulk-export-data.rst deleted file mode 100644 index bb4ba53468a..00000000000 --- a/source/manage/bulk-export-data.rst +++ /dev/null @@ -1,757 +0,0 @@ -:nosearch: - -Bulk export data ----------------- - -.. tab:: Use mmctl - - 1. Create a full export file including attachments by running the :ref:`mmctl export create -- attachments ` command. See the :ref:`Mattermost data migration ` documentation for details. - - 2. While the job is running, you can check its status by running the :ref:`mmctl export job show ` command. - - 3. When the export job status is successful: - - a. Identify the name of the completed export file by running the :ref:`mmctl export list ` command. - b. Download the export file to your local machine by running the :ref:`mmctl export download ` command. - -.. tab:: Use CLI - - .. note:: - - From Mattermost v6.0, this command has been deprecated in favor of :ref:`mmctl export commands ` as the supported way to export data out of Mattermost. - - The export command runs in the :doc:`CLI `. It has permissions to access all information in the Mattermost database. - - To run the export command: - - 1. Navigate to the directory where the Mattermost server is installed. On a default install of Mattermost, the directory is ``/opt/mattermost``. - 2. Run the following command to extract data from all teams on the server. Note that you can change the file name and specify an absolute or relative path to dictate where the file is exported: - - ``sudo -u mattermost bin/mattermost export bulk file.json --all-teams`` - - ``sudo -u mattermost bin/mattermost export bulk /home/user/bulk_data.json --all-teams`` - - 3. Retrieve your file from the location you specified. - -At this time, the export supports attributes of the objects listed below. All Mattermost bulk export data files will begin with a ``Version`` object as the first line of the file. This indicates the version of the Mattermost bulk import file format with which the exported data is compatible. - -You can export the following data types: - -- Teams -- Threaded discussions -- Channels (public, private, and direct) -- Users -- Users' team memberships -- Users' channel memberships -- Users' notification preferences -- Posts (regular, non-reply messages) -- Posts' replies and threads in public or private channels -- Posts' reactions -- Custom emoji -- Direct message and group message channels -- Direct message and group message channels' read/unread status -- Direct message posts -- Roles -- Permissions schemes - -.. note:: - - Configuration for data types such as exporting specific areas of the server, exporting additional types of posts, file attachments, webhooks, and bot messages is not yet supported. Deleted objects are also not yet supported. - - For requests to add additional attributes or objects to our exporter, please add a feature request on our `feature idea forum `__. - -Version object --------------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - -
Field nameTypeDescription
typestringThe string "version"
versionnumberThe number 1.
infoobjectOptional VersionInfo object
- -VersionInfo object ------------------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Field nameTypeDescription
generatorstringThe name of the tool this export was generated with. Well known tools are:
- "mattermost-server" for the Mattermost Server.
- "mmetl" for the Slack export converter "mmetl".
versionstringThe version of the tool this export was generated with. This may contain multiple pieces of version info, separated by spaces. The first one should be a semantic version.
- "7.6.0 (29bb1e53ef5a439c73065f47de2972f9bbcb09a4, enterprise: true)" is an example of such a version string.
createdstringThe timestamp of the file creation. This should be formatted as an RFC 3339 timestamp. The nanosecond part is optional.
- "2022-11-22T16:40:51.019582328+01:00"
additionalanyAny additional information the generator wants to include into the file header. May be omitted. Be aware that the size of each line is limited to a few MiB.
- -Team object ------------ - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Field nameTypeDescription
namestringThe team name.
display_namestringThe display name for the team.
typestringThe type of team. Will have one of the following values:
- "O" for an open team
- "I" for an invite-only team.
descriptionstringThe team description.
allow_open_inviteboolWhether to allow open invitations. Will have one of the following values:
- "true"
- "false"
schemestringThe name of the permissions scheme that applies to this team.
- -Channel object --------------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Field nameTypeDescription
teamstringThe name of the team this channel belongs to.
namestringThe name of the channel.
display_namestringThe display name for the channel.
typestringThe type of channel. Will have one the following values:
- "O" for a public channel.
- "P" for a private channel.
headerstringThe channel header.
purposestringThe channel purpose.
schemestringThe name of the permissions scheme that applies to this team.
- -User object ------------ - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Field nameTypeDescription
usernamestringThe user’s username. This is the unique identifier for the user.
emailstringThe user’s email address.
auth_servicestringThe authentication service used for this user account. This field will be absent for user/password authentication.
- "gitlab" - GitLab authentication.
- "ldap" - LDAP authentication (Enterprise and Professional)
- "saml" - Generic SAML based authentication (Enterprise)
- "google" - Google OAuth authentication (Enterprise)
- "entra id" - Microsoft Entra ID OAuth Authentication (Enterprise)
auth_datastringThe authentication data if auth_service is used. The value depends on the auth_service that is specified.
- The data comes from the following fields for the respective auth_services:
- "gitlab" - The value of the Id attribute provided in the GitLab auth data.
- "ldap" - The value of the LDAP attribute specified as the "ID Attribute" in the Mattermost LDAP configuration.
- "saml" - The value of the SAML email address attribute.
- "google" - The value of the OAuth Id attribute.
- "office365" - The value of the OAuth Id attribute.
nicknamestringThe user’s nickname.
first_namestringThe user’s first name.
last_namestringThe user’s last name.
positionstringThe user’s position.
rolesstringThe user’s roles.
localestringThe user’s localization configuration.
use_markdown_previewbool"true" if the user has enabled markdown preview in the message input box.
use_formattingbool"true" if the user has enabled post formatting for links, emoji, text styles, and line breaks.
show_unread_sectionstring"true" if the user has enabled showing unread messages at top of channel sidebar.
themestringThe user’s theme. Formatted as a Mattermost theme string.
military_timestring"true" if the user has enabled a 24-hour clock. "false" if using a 12-hour clock.
collapse_previewsstring"true" if user collapses link preview by default. "false" if user expands link previews by default.
message_displaystringThe style the user prefers for displayed messages. Options are "clean" if the user uses the standard style or "compact" if the user uses compact style.
channel_display_modestring"full" if the users displays channel messages at the full width of the screen or "centered" if the user uses a fixed width, centered block.
tutorial_stepstring"1", "2", or "3" indicates which specified tutorial step to start with for the user. "999" skips the tutorial.
email_intervalstringEmail batching interval to use during bulk import.
delete_atint64Timestamp of when the user was deactivated.
teamsarrayThe teams which the user is member of. Is an array of UserTeamMembership objects.
notify_propsobjectThe user’s notify preferences, as defined by the UserNotifyProps object.
- -UserNotifyProps object ----------------------- - -This object is a member of the User object. - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Field nameTypeDescription
desktopstringPreference for sending desktop notifications. Will be one of the following values:
- "all" - For all activity.
- "mention" - Only for mentions.
- "none" - Never.
desktop_soundstringPreference for whether desktop notification sound is played. Will be one of the following values:
- "true" - Sound is played.
- "false" - Sound is not played.
emailstringPreference for email notifications. Will be one of the following values:
- "true" - Email notifications are sent immediately.
- "false" - Email notifications are not sent.
mobilestringPreference for sending mobile push notifications. Will be one of the following values:
- "all" - For all activity.
- "mention" - Only for mentions.
- "none" - Never.
mobile_push_statusstringPreference for when push notifications are triggered. Will be one of the following values:
- "online" - When online, away or offline.
- "away" - When away or offline.
- "offline" - When offline.
channelstringPreference for whether @all, @channel, and @here trigger mentions. Will be one of the following values:
- "true" - Mentions are triggered.
- "false" - Mentions are not triggered.
commentsstringPreference for reply mention notifications. Will be one of the following values:
- "any" - Trigger notifications on messages in reply threads that the user starts or participates in.
- "root" - Trigger notifications on messages in threads that the user starts.
- "never" - Do not trigger notifications on messages in reply threads unless the user is mentioned.
mention_keysstringPreference for custom non-case sensitive words that trigger mentions. Words are separated by commas.
- -UserTeamMembership object -------------------------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Field nameTypeDescription
namestringThe name of the team this user is a member of.
rolesstringThe roles the user has within this team.
themestringThe user’s theme for this team. Formatted as a Mattermost theme string.
channelsarrayThe channels within this team that the user is a member of. Listed as an array of UserChannelMembership objects.
- -UserChannelMembership object ----------------------------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Field nameTypeDescription
namestringThe name of the channel in the parent team that this user is a member of.
rolesstringThe roles the user has within this channel.
notify_propsobjectThe notify preferences for this user in this channel as defined by the ChannelNotifyProps object.
favoritebooleanWhether the channel is marked as a favorite for this user. Will be one of the following values:
- "true" - Yes.
- "false" - No.
mention_countint64The mention preferences for this user in this channel as defined by the ChannelMentionCount object.
mention_count_rootint64The mention preferences for this user in this channel as defined by the ChannelMentionCountRoot object.
urgent_mention_countint64The mention preferences for this user in this channel as defined by the UrgendMentionCount object.
msg_countint64The mention preferences for this user in this channel as defined by the MsgCount object.
msg_count_rootint64The mention preferences for this user in this channel as defined by the MsgCountRoot object.
last_viewed_atint64The mention preferences for this user in this channel as defined by the LastViewedAt object.
- -ChannelNotifyProps object -~~~~~~~~~~~~~~~~~~~~~~~~~ - -This object is a member of the ChannelMembership object. - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - -
Field nameTypeDescription
desktopstringPreference for sending desktop notifications. Will be one of the following values:
- "default" - Global default.
- "all" - For all activity.
- "mention" - Only for mentions.
- "none" - Never.
mobilestringPreference for sending mobile notifications. Will be one of the following values:
- "default" - Global default.
- "all" - For all activity.
- "mention" - Only for mentions.
- "none" - Never.
mark_unreadstringPreference for marking channel as unread. Will be one of the following values:
- "all" - For all unread messages.
- "mention" - Only for mentions.
- -Post object ------------ - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Field nameTypeDescription
teamstringThe name of the team that this post is in.
channelstringThe name of the channel that this post is in.
userstringThe username of the user for this post.
messagestringThe message that the post contains.
propsobjectThe props for a post. Contains additional formatting information used by integrations and bot posts. For a more detailed explanation see the message attachments documentation.
create_atintThe timestamp for the post, in milliseconds since the Unix epoch.
reactionsarrayThe emoji reactions to this post. Will be an array of Reaction objects.
- -Reply object ------------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - -
Field nameTypeDescription
userstringThe username of the user for this reply.
messagestringThe message that the reply contains.
create_atintThe timestamp for the reply, in milliseconds since the Unix epoch.
- -Reaction object ---------------- - -This object is a member of the Post object. - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - -
Field nameTypeDescription
userstringThe username of the user for this reply.
emoji_namestringThe emoji of the reaction.
create_atintThe timestamp for the reply, in milliseconds since the Unix epoch.
- -Emoji object ------------- - -.. raw:: html - - - - - - - - - - - - - - - - - -
Field nameTypeDescription
namestringThe emoji name.
imagestringThe path (either absolute or relative to the current working directory) to the image file for this emoji.
- -DirectChannel object --------------------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - -
Field nameTypeDescription
membersarrayList of channel members.
favorited_byarrayList of channel members who have favorited the direct channel.
headerstringThe channel header.
- -DirectPost object ------------------ - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - -
Field nameTypeDescription
userstringThe username of the user for this post.
messagestringThe message that the post contains.
create_atintThe timestamp for the post, in milliseconds since the Unix epoch.
diff --git a/source/manage/bulk-export-tool.rst b/source/manage/bulk-export-tool.rst index 5a0a94a1650..4e14b98259f 100644 --- a/source/manage/bulk-export-tool.rst +++ b/source/manage/bulk-export-tool.rst @@ -22,5 +22,758 @@ You can export the following data types: - Direct message and group message channels' read/unread status - Posts (messages in public or private channels and replies to those messages) -.. include:: bulk-export-data.rst - :start-after: :nosearch: +Bulk export data +---------------- + +.. tab:: Use mmctl + + 1. Create a full export file including attachments by running the :ref:`mmctl export create -- attachments ` command. See the :ref:`Mattermost data migration ` documentation for details. + + 2. While the job is running, you can check its status by running the :ref:`mmctl export job show ` command. + + 3. When the export job status is successful: + + a. Identify the name of the completed export file by running the :ref:`mmctl export list ` command. + b. Download the export file to your local machine by running the :ref:`mmctl export download ` command. + +.. tab:: Use CLI + + .. note:: + + From Mattermost v6.0, this command has been deprecated in favor of :ref:`mmctl export commands ` as the supported way to export data out of Mattermost. + + The export command runs in the :doc:`CLI `. It has permissions to access all information in the Mattermost database. + + To run the export command: + + 1. Navigate to the directory where the Mattermost server is installed. On a default install of Mattermost, the directory is ``/opt/mattermost``. + 2. Run the following command to extract data from all teams on the server. Note that you can change the file name and specify an absolute or relative path to dictate where the file is exported: + + ``sudo -u mattermost bin/mattermost export bulk file.json --all-teams`` + + ``sudo -u mattermost bin/mattermost export bulk /home/user/bulk_data.json --all-teams`` + + 3. Retrieve your file from the location you specified. + +At this time, the export supports attributes of the objects listed below. All Mattermost bulk export data files will begin with a ``Version`` object as the first line of the file. This indicates the version of the Mattermost bulk import file format with which the exported data is compatible. + +You can export the following data types: + +- Teams +- Threaded discussions +- Channels (public, private, and direct) +- Users +- Users' team memberships +- Users' channel memberships +- Users' notification preferences +- Posts (regular, non-reply messages) +- Posts' replies and threads in public or private channels +- Posts' reactions +- Custom emoji +- Direct message and group message channels +- Direct message and group message channels' read/unread status +- Direct message posts +- Roles +- Permissions schemes + +.. note:: + + Configuration for data types such as exporting specific areas of the server, exporting additional types of posts, file attachments, webhooks, and bot messages is not yet supported. Deleted objects are also not yet supported. + + For requests to add additional attributes or objects to our exporter, please add a feature request on our `feature idea forum `__. + +Version object +-------------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + +
Field nameTypeDescription
typestringThe string "version"
versionnumberThe number 1.
infoobjectOptional VersionInfo object
+ +VersionInfo object +------------------ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field nameTypeDescription
generatorstringThe name of the tool this export was generated with. Well known tools are:
+ "mattermost-server" for the Mattermost Server.
+ "mmetl" for the Slack export converter "mmetl".
versionstringThe version of the tool this export was generated with. This may contain multiple pieces of version info, separated by spaces. The first one should be a semantic version.
+ "7.6.0 (29bb1e53ef5a439c73065f47de2972f9bbcb09a4, enterprise: true)" is an example of such a version string.
createdstringThe timestamp of the file creation. This should be formatted as an RFC 3339 timestamp. The nanosecond part is optional.
+ "2022-11-22T16:40:51.019582328+01:00"
additionalanyAny additional information the generator wants to include into the file header. May be omitted. Be aware that the size of each line is limited to a few MiB.
+ +Team object +----------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field nameTypeDescription
namestringThe team name.
display_namestringThe display name for the team.
typestringThe type of team. Will have one of the following values:
+ "O" for an open team
+ "I" for an invite-only team.
descriptionstringThe team description.
allow_open_inviteboolWhether to allow open invitations. Will have one of the following values:
+ "true"
+ "false"
schemestringThe name of the permissions scheme that applies to this team.
+ +Channel object +-------------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field nameTypeDescription
teamstringThe name of the team this channel belongs to.
namestringThe name of the channel.
display_namestringThe display name for the channel.
typestringThe type of channel. Will have one the following values:
+ "O" for a public channel.
+ "P" for a private channel.
headerstringThe channel header.
purposestringThe channel purpose.
schemestringThe name of the permissions scheme that applies to this team.
+ +User object +----------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field nameTypeDescription
usernamestringThe user’s username. This is the unique identifier for the user.
emailstringThe user’s email address.
auth_servicestringThe authentication service used for this user account. This field will be absent for user/password authentication.
+ "gitlab" - GitLab authentication.
+ "ldap" - LDAP authentication (Enterprise and Professional)
+ "saml" - Generic SAML based authentication (Enterprise)
+ "google" - Google OAuth authentication (Enterprise)
+ "entra id" - Microsoft Entra ID OAuth Authentication (Enterprise)
auth_datastringThe authentication data if auth_service is used. The value depends on the auth_service that is specified.
+ The data comes from the following fields for the respective auth_services:
+ "gitlab" - The value of the Id attribute provided in the GitLab auth data.
+ "ldap" - The value of the LDAP attribute specified as the "ID Attribute" in the Mattermost LDAP configuration.
+ "saml" - The value of the SAML email address attribute.
+ "google" - The value of the OAuth Id attribute.
+ "office365" - The value of the OAuth Id attribute.
nicknamestringThe user’s nickname.
first_namestringThe user’s first name.
last_namestringThe user’s last name.
positionstringThe user’s position.
rolesstringThe user’s roles.
localestringThe user’s localization configuration.
use_markdown_previewbool"true" if the user has enabled markdown preview in the message input box.
use_formattingbool"true" if the user has enabled post formatting for links, emoji, text styles, and line breaks.
show_unread_sectionstring"true" if the user has enabled showing unread messages at top of channel sidebar.
themestringThe user’s theme. Formatted as a Mattermost theme string.
military_timestring"true" if the user has enabled a 24-hour clock. "false" if using a 12-hour clock.
collapse_previewsstring"true" if user collapses link preview by default. "false" if user expands link previews by default.
message_displaystringThe style the user prefers for displayed messages. Options are "clean" if the user uses the standard style or "compact" if the user uses compact style.
channel_display_modestring"full" if the users displays channel messages at the full width of the screen or "centered" if the user uses a fixed width, centered block.
tutorial_stepstring"1", "2", or "3" indicates which specified tutorial step to start with for the user. "999" skips the tutorial.
email_intervalstringEmail batching interval to use during bulk import.
delete_atint64Timestamp of when the user was deactivated.
teamsarrayThe teams which the user is member of. Is an array of UserTeamMembership objects.
notify_propsobjectThe user’s notify preferences, as defined by the UserNotifyProps object.
+ +UserNotifyProps object +---------------------- + +This object is a member of the User object. + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field nameTypeDescription
desktopstringPreference for sending desktop notifications. Will be one of the following values:
+ "all" - For all activity.
+ "mention" - Only for mentions.
+ "none" - Never.
desktop_soundstringPreference for whether desktop notification sound is played. Will be one of the following values:
+ "true" - Sound is played.
+ "false" - Sound is not played.
emailstringPreference for email notifications. Will be one of the following values:
+ "true" - Email notifications are sent immediately.
+ "false" - Email notifications are not sent.
mobilestringPreference for sending mobile push notifications. Will be one of the following values:
+ "all" - For all activity.
+ "mention" - Only for mentions.
+ "none" - Never.
mobile_push_statusstringPreference for when push notifications are triggered. Will be one of the following values:
+ "online" - When online, away or offline.
+ "away" - When away or offline.
+ "offline" - When offline.
channelstringPreference for whether @all, @channel, and @here trigger mentions. Will be one of the following values:
+ "true" - Mentions are triggered.
+ "false" - Mentions are not triggered.
commentsstringPreference for reply mention notifications. Will be one of the following values:
+ "any" - Trigger notifications on messages in reply threads that the user starts or participates in.
+ "root" - Trigger notifications on messages in threads that the user starts.
+ "never" - Do not trigger notifications on messages in reply threads unless the user is mentioned.
mention_keysstringPreference for custom non-case sensitive words that trigger mentions. Words are separated by commas.
+ +UserTeamMembership object +------------------------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field nameTypeDescription
namestringThe name of the team this user is a member of.
rolesstringThe roles the user has within this team.
themestringThe user’s theme for this team. Formatted as a Mattermost theme string.
channelsarrayThe channels within this team that the user is a member of. Listed as an array of UserChannelMembership objects.
+ +UserChannelMembership object +---------------------------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field nameTypeDescription
namestringThe name of the channel in the parent team that this user is a member of.
rolesstringThe roles the user has within this channel.
notify_propsobjectThe notify preferences for this user in this channel as defined by the ChannelNotifyProps object.
favoritebooleanWhether the channel is marked as a favorite for this user. Will be one of the following values:
+ "true" - Yes.
+ "false" - No.
mention_countint64The mention preferences for this user in this channel as defined by the ChannelMentionCount object.
mention_count_rootint64The mention preferences for this user in this channel as defined by the ChannelMentionCountRoot object.
urgent_mention_countint64The mention preferences for this user in this channel as defined by the UrgendMentionCount object.
msg_countint64The mention preferences for this user in this channel as defined by the MsgCount object.
msg_count_rootint64The mention preferences for this user in this channel as defined by the MsgCountRoot object.
last_viewed_atint64The mention preferences for this user in this channel as defined by the LastViewedAt object.
+ +ChannelNotifyProps object +~~~~~~~~~~~~~~~~~~~~~~~~~ + +This object is a member of the ChannelMembership object. + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + +
Field nameTypeDescription
desktopstringPreference for sending desktop notifications. Will be one of the following values:
+ "default" - Global default.
+ "all" - For all activity.
+ "mention" - Only for mentions.
+ "none" - Never.
mobilestringPreference for sending mobile notifications. Will be one of the following values:
+ "default" - Global default.
+ "all" - For all activity.
+ "mention" - Only for mentions.
+ "none" - Never.
mark_unreadstringPreference for marking channel as unread. Will be one of the following values:
+ "all" - For all unread messages.
+ "mention" - Only for mentions.
+ +Post object +----------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field nameTypeDescription
teamstringThe name of the team that this post is in.
channelstringThe name of the channel that this post is in.
userstringThe username of the user for this post.
messagestringThe message that the post contains.
propsobjectThe props for a post. Contains additional formatting information used by integrations and bot posts. For a more detailed explanation see the message attachments documentation.
create_atintThe timestamp for the post, in milliseconds since the Unix epoch.
reactionsarrayThe emoji reactions to this post. Will be an array of Reaction objects.
+ +Reply object +------------ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + +
Field nameTypeDescription
userstringThe username of the user for this reply.
messagestringThe message that the reply contains.
create_atintThe timestamp for the reply, in milliseconds since the Unix epoch.
+ +Reaction object +--------------- + +This object is a member of the Post object. + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + +
Field nameTypeDescription
userstringThe username of the user for this reply.
emoji_namestringThe emoji of the reaction.
create_atintThe timestamp for the reply, in milliseconds since the Unix epoch.
+ +Emoji object +------------ + +.. raw:: html + + + + + + + + + + + + + + + + + +
Field nameTypeDescription
namestringThe emoji name.
imagestringThe path (either absolute or relative to the current working directory) to the image file for this emoji.
+ +DirectChannel object +-------------------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + +
Field nameTypeDescription
membersarrayList of channel members.
favorited_byarrayList of channel members who have favorited the direct channel.
headerstringThe channel header.
+ +DirectPost object +----------------- + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + +
Field nameTypeDescription
userstringThe username of the user for this post.
messagestringThe message that the post contains.
create_atintThe timestamp for the post, in milliseconds since the Unix epoch.
\ No newline at end of file diff --git a/source/manage/common-support-packet.rst b/source/manage/common-support-packet.rst deleted file mode 100644 index 0ceb16931b7..00000000000 --- a/source/manage/common-support-packet.rst +++ /dev/null @@ -1,135 +0,0 @@ -:nosearch: - -Use the System Console or the :ref:`mmctl system supportpacket ` command to generate a Mattermost Support Packet that includes configuration information, logs, plugin details, and data on external dependencies across all nodes in a high-availability cluster. Confidential data, such as passwords, are automatically stripped. - -Contents of a Support Packet ----------------------------- - -A Mattermost Support Packet can contain the following files: - -- `metadata.yaml <#metadata>`__ -- ``mattermost.log`` -- ``plugins.json`` -- ``sanitized_config.json`` -- ``support_packet.yaml`` -- `Go performance metrics <#go-performance-metrics>`__, including: ``cpu.prof``, ``heap.prof``, and ``goroutines`` -- ``warning.txt`` (present when issues are encountered during packet generation) - -.. note:: - - - Each node in the cluster of a :doc:`high availability ` deployment has its own ``mattermost.log`` file. - - LDAP groups are not included during Support Packet generation. Only ``LDAP Version`` and ``LDAP Vendor`` are included when present. These values are included in the ``support_packet.yaml`` file. - - From Mattermost v9.11, ``LDAP Vendor`` errors are included in the Support Packet. If fetching the LDAP Vendor name fails, the Support Packet generation includes the error in ``warning.txt``. If no LDAP Vendor name is found, the Support Packet lists them as ``unknown``. - -Generate ---------- - -.. important:: - - Before generating a Support Packet, go to **System Console > Environment > Logging** and ensure **Output logs to file** is set to **true**, and set **File Log Level** to **DEBUG**. - -.. tab:: Web/Desktop - - 1. Go to the System Console, and select **Commercial Support** from the System Console menu. - - .. image:: ../images/system-console-commercial-support.png - :alt: Example of available System Console menu options. - - 2. Select **Download Support Packet**. A zip file is downloaded to the local machine. You'll be notified if any packet files are unavailable during packet generation. See the ``warning.txt`` file for details. - -.. tab:: mmctl - - Run the :ref:`mmctl system supportpacket ` command to generate and download a Support Packet to share with Mattermost Support. - - .. code-block:: sh - - go run ./cmd/mmctl system supportpacket - - .. code-block:: text - - Downloading Support Packet - Downloaded Support Packet to mattermost_support_packet_.zip - -Santitize confidential data ---------------------------- - -When present, the following information is santized during packet generation: ``LdapSettings.BindPassword``, ``FileSettings.PublicLinkSalt``, ``FileSettings.AmazonS3SecretAccessKey``, ``EmailSettings.SMTPPassword``, ``GitLabSettings.Secret``, ``GoogleSettings.Secret``, ``Office365Settings.Secret``, ``OpenIdSettings.Secret``, ``SqlSettings.DataSource``, ``SqlSettings.AtRestEncryptKey``, ``ElasticsearchSettings.Password``, ``All SqlSettings.DataSourceReplicas``, ``All SqlSettings.DataSourceSearchReplicas``, ``MessageExportSettings.GlobalRelaySettings.SmtpPassword``, and ``ServiceSettings.SplitKey``. Plugins are not sanitized during packet generation. - -Ensure you sanitize any additional confidential details in the ``plugin.json`` file before sharing it with Mattermost. Replace details with example strings that contain the same special characters if possible, as special characters are common causes of configuration errors. - -Share the packet with Mattermost --------------------------------- - -Add the generated Support Packet to a `standard support request `_, or share with with the Mattermost team you're working with. - -.. important:: - - Disable debug logging once you've generated the Support Packet. Debug logging can cause log files to expand substantially, and may adversely impact server performance. We recommend enabling it temporarily, or in development environments, but not production enviornments. - -Metadata ---------- - -From Mattermost v9.11, generated Support Packets include a ``metadata.yaml`` file that contains the following information. - -+-----------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+----------------------------+ -| **Field name** | **Required/Optional** | **Description** | **Example** | -+=======================+=======================+===================================================================================================================+============================+ -| version | Required | Version of the schema that the current metadata file is compatible with. | 1 | -| | | Current version is 1. | | -+-----------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+----------------------------+ -| type | Required | The type of the packet. | mattermost | -| | | Each type of Support Packet can be mapped to a specific component generating the Support Packet. | | -+-----------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+----------------------------+ -| generated_at | Required | The date and time the packet was created. | 1707473288731 | -| | | Value is in epoch (ms). | | -+-----------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+----------------------------+ -| server_version | Required | Version of the server that the Support Packet was generated at. | 9.1.1 | -| | | Semver is expected. | | -+-----------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+----------------------------+ -| server_id | Required | Unique identifier of the server. | 9qpiszyjr3g8bxda35abcd1234 | -| | | Expected to be 26 characters or longer. | | -+-----------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+----------------------------+ -| license_id | Optional | Unique identifier of the current server's license. | abcdejisd67yigqhmkz4ho1234 | -| | | Expected to be 26 characters or longer. | | -| | | This field is empty when there’s no license. | | -+-----------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+----------------------------+ -| customer_id | Optional | The id of the customer, as defined in the license file. | a1b2c3d4qbbr5cpkbpbmef123h | -| | | Expected to be 26 characters or longer. | | -| | | Empty when there’s no license. | | -+-----------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+----------------------------+ -| extras | Optional | Key/value of any additional information, specific to the plugin/component that generated the file. | | -| | | Can be useful for identifying the contents of the data. | | -| | | Consider adding plugin (or component) versions in order to set expectation regarding the contents of this object. | | -+-----------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+----------------------------+ -| extras.plugin_id | Required for plugins | The ID of the plugin. | | -+-----------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+----------------------------+ -| extras.plugin_version | Required for plugins | The version of the plugin. | | -+-----------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+----------------------------+ - -For example: - -.. code-block:: yaml - :class: mm-code-block - - version: 1 - type: support-packet - generated_at: 1622569200 - server_version: 9.1.1 - server_id: 8fqk9rti13fmpxdd5934a3xsxh - license_id: 3g3pqn8in3brzjkozcn1kdidgr - customer_id: 74cmws7gf3ykpj31car7zahsny - extras: - plugin_version: 0.1.0 - -Go performance metrics ----------------------- - -The Support Packet contains 3 go runtime profiling files: - -- ``cpu.prof`` contains a 5-second CPU profile -- ``heap.prof`` contains a heap profile -- ``goroutines`` contains a dump of all the running go routines - -These files can be read using `pprof `__. - -Use ``go tool pprof -web X`` to open a visualization of the profile in your browser, replacing ``X`` with the profile's file name. diff --git a/source/manage/generating-support-packet.rst b/source/manage/generating-support-packet.rst index ef27d5ef65e..57f1a3fe93f 100644 --- a/source/manage/generating-support-packet.rst +++ b/source/manage/generating-support-packet.rst @@ -8,5 +8,136 @@ Generate a Support Packet

Also available in legacy Mattermost Enterprise Edition E10 or E20

-.. include:: common-support-packet.rst - :start-after: :nosearch: +Use the System Console or the :ref:`mmctl system supportpacket ` command to generate a Mattermost Support Packet that includes configuration information, logs, plugin details, and data on external dependencies across all nodes in a high-availability cluster. Confidential data, such as passwords, are automatically stripped. + +Contents of a Support Packet +---------------------------- + +A Mattermost Support Packet can contain the following files: + +- `metadata.yaml <#metadata>`__ +- ``mattermost.log`` +- ``plugins.json`` +- ``sanitized_config.json`` +- ``support_packet.yaml`` +- `Go performance metrics <#go-performance-metrics>`__, including: ``cpu.prof``, ``heap.prof``, and ``goroutines`` +- ``warning.txt`` (present when issues are encountered during packet generation) + +.. note:: + + - Each node in the cluster of a :doc:`high availability ` deployment has its own ``mattermost.log`` file. + - LDAP groups are not included during Support Packet generation. Only ``LDAP Version`` and ``LDAP Vendor`` are included when present. These values are included in the ``support_packet.yaml`` file. + - From Mattermost v9.11, ``LDAP Vendor`` errors are included in the Support Packet. If fetching the LDAP Vendor name fails, the Support Packet generation includes the error in ``warning.txt``. If no LDAP Vendor name is found, the Support Packet lists them as ``unknown``. + +Generate +--------- + +.. important:: + + Before generating a Support Packet, go to **System Console > Environment > Logging** and ensure **Output logs to file** is set to **true**, and set **File Log Level** to **DEBUG**. + +.. tab:: Web/Desktop + + 1. Go to the System Console, and select **Commercial Support** from the System Console menu. + + .. image:: ../images/system-console-commercial-support.png + :alt: Example of available System Console menu options. + + 2. Select **Download Support Packet**. A zip file is downloaded to the local machine. You'll be notified if any packet files are unavailable during packet generation. See the ``warning.txt`` file for details. + +.. tab:: mmctl + + Run the :ref:`mmctl system supportpacket ` command to generate and download a Support Packet to share with Mattermost Support. + + .. code-block:: sh + + go run ./cmd/mmctl system supportpacket + + .. code-block:: text + + Downloading Support Packet + Downloaded Support Packet to mattermost_support_packet_.zip + +Santitize confidential data +--------------------------- + +When present, the following information is santized during packet generation: ``LdapSettings.BindPassword``, ``FileSettings.PublicLinkSalt``, ``FileSettings.AmazonS3SecretAccessKey``, ``EmailSettings.SMTPPassword``, ``GitLabSettings.Secret``, ``GoogleSettings.Secret``, ``Office365Settings.Secret``, ``OpenIdSettings.Secret``, ``SqlSettings.DataSource``, ``SqlSettings.AtRestEncryptKey``, ``ElasticsearchSettings.Password``, ``All SqlSettings.DataSourceReplicas``, ``All SqlSettings.DataSourceSearchReplicas``, ``MessageExportSettings.GlobalRelaySettings.SmtpPassword``, and ``ServiceSettings.SplitKey``. Plugins are not sanitized during packet generation. + +Ensure you sanitize any additional confidential details in the ``plugin.json`` file before sharing it with Mattermost. Replace details with example strings that contain the same special characters if possible, as special characters are common causes of configuration errors. + +Share the packet with Mattermost +-------------------------------- + +Add the generated Support Packet to a `standard support request `_, or share with with the Mattermost team you're working with. + +.. important:: + + Disable debug logging once you've generated the Support Packet. Debug logging can cause log files to expand substantially, and may adversely impact server performance. We recommend enabling it temporarily, or in development environments, but not production enviornments. + +Metadata +--------- + +From Mattermost v9.11, generated Support Packets include a ``metadata.yaml`` file that contains the following information. + ++-----------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+----------------------------+ +| **Field name** | **Required/Optional** | **Description** | **Example** | ++=======================+=======================+===================================================================================================================+============================+ +| version | Required | Version of the schema that the current metadata file is compatible with. | 1 | +| | | Current version is 1. | | ++-----------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+----------------------------+ +| type | Required | The type of the packet. | mattermost | +| | | Each type of Support Packet can be mapped to a specific component generating the Support Packet. | | ++-----------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+----------------------------+ +| generated_at | Required | The date and time the packet was created. | 1707473288731 | +| | | Value is in epoch (ms). | | ++-----------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+----------------------------+ +| server_version | Required | Version of the server that the Support Packet was generated at. | 9.1.1 | +| | | Semver is expected. | | ++-----------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+----------------------------+ +| server_id | Required | Unique identifier of the server. | 9qpiszyjr3g8bxda35abcd1234 | +| | | Expected to be 26 characters or longer. | | ++-----------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+----------------------------+ +| license_id | Optional | Unique identifier of the current server's license. | abcdejisd67yigqhmkz4ho1234 | +| | | Expected to be 26 characters or longer. | | +| | | This field is empty when there’s no license. | | ++-----------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+----------------------------+ +| customer_id | Optional | The id of the customer, as defined in the license file. | a1b2c3d4qbbr5cpkbpbmef123h | +| | | Expected to be 26 characters or longer. | | +| | | Empty when there’s no license. | | ++-----------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+----------------------------+ +| extras | Optional | Key/value of any additional information, specific to the plugin/component that generated the file. | | +| | | Can be useful for identifying the contents of the data. | | +| | | Consider adding plugin (or component) versions in order to set expectation regarding the contents of this object. | | ++-----------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+----------------------------+ +| extras.plugin_id | Required for plugins | The ID of the plugin. | | ++-----------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+----------------------------+ +| extras.plugin_version | Required for plugins | The version of the plugin. | | ++-----------------------+-----------------------+-------------------------------------------------------------------------------------------------------------------+----------------------------+ + +For example: + +.. code-block:: yaml + :class: mm-code-block + + version: 1 + type: support-packet + generated_at: 1622569200 + server_version: 9.1.1 + server_id: 8fqk9rti13fmpxdd5934a3xsxh + license_id: 3g3pqn8in3brzjkozcn1kdidgr + customer_id: 74cmws7gf3ykpj31car7zahsny + extras: + plugin_version: 0.1.0 + +Go performance metrics +---------------------- + +The Support Packet contains 3 go runtime profiling files: + +- ``cpu.prof`` contains a 5-second CPU profile +- ``heap.prof`` contains a heap profile +- ``goroutines`` contains a dump of all the running go routines + +These files can be read using `pprof `__. + +Use ``go tool pprof -web X`` to open a visualization of the profile in your browser, replacing ``X`` with the profile's file name. \ No newline at end of file diff --git a/source/onboard/bulk-loading-about.rst b/source/onboard/bulk-loading-about.rst deleted file mode 100644 index dfc2d7fd07f..00000000000 --- a/source/onboard/bulk-loading-about.rst +++ /dev/null @@ -1,24 +0,0 @@ -:orphan: -:nosearch: - -About the bulk loading command ------------------------------- - -**The bulk loading command is interruptible and idempotent** - -If the import is interrupted for any reason, it continues from where it left off the next time you run it. You can run the command repeatedly with the same data file, and the data is imported only once. Posts with matching timestamps to incoming posts will have their attachments replaced by the incoming data. Prior to v5.20 any updates to posts with matching timestamps were appended to older posts. - -**You can run the bulk loading command on a live system** - -Although you don't need to shut down Mattermost to run the command, changes made by users of the system between runs can be overwritten if the corresponding fields exist in the data file. - -**Some data fields are optional** - -Not all fields are mandatory. If an optional field is missing from the object that is being imported, the field's current value in the database is not changed. - -**The bulk loading command is not a synchronization tool** - -You cannot use the bulk loading command to remove any objects or their fields from the Mattermost database. The command only creates or overwrites fields. - -.. important:: - The bulk loading command runs in the mmctl and operates in the security context of the mmctl. This means it has full permissions to access and alter everything in the Mattermost database. diff --git a/source/onboard/bulk-loading-common-issues.rst b/source/onboard/bulk-loading-common-issues.rst deleted file mode 100644 index 9d5dc94530e..00000000000 --- a/source/onboard/bulk-loading-common-issues.rst +++ /dev/null @@ -1,13 +0,0 @@ -:orphan: -:nosearch: - -Common issues -------------- - -Run the bulk import command as the *mattermost* user. Running it as *root* or any other user will cause issues with file permissions on imported attachments. - -Ensure that :ref:`file attachments are enabled `, that you have enough free space in your :ref:`file storage system ` to support the incoming attachments, and that your :ref:`maximum file size ` is appropriate. - -Make sure you have enough free space for logs on the Mattermost server as well as free space on the database server for both the database itself and transaction logs. - -Disable anti-virus or any other plugins that might interfere with attachment uploading. They could potentially block uploading of attachments and cause the import to fail if configured incorrectly. If you need anti-virus scanning, scan the attachment folder before the import. diff --git a/source/onboard/bulk-loading-data-format.rst b/source/onboard/bulk-loading-data-format.rst deleted file mode 100644 index 6ca597c18d1..00000000000 --- a/source/onboard/bulk-loading-data-format.rst +++ /dev/null @@ -1,1522 +0,0 @@ -:orphan: -:nosearch: - -Data format ------------ - -The input data file must be a valid `JSONL `__ file with the following objects, each on its own line in the file. The objects must occur in the file in the order listed. - -Version - Mandatory. The Version object must be the first line in the file, and must occur only once. The version is the version of the bulk importer tool, which is currently ``1``. -Scheme - Optional. If present, Scheme objects must occur after the Version object but before any Team objects. -Emoji - Optional. If present, Emoji objects must occur after the Version objects but before any Team objects. -Team - Optional. If present, Team objects must occur after any Scheme objects and before any Channel objects. -Channel - Optional. If present, Channel objects must occur after all Team objects and before any User objects. -User - Optional. If present, User objects must occur after the Team and Channel objects in the file and before any Post objects. Each User object defines the teams and channels that the user is a member of. If the corresponding teams and channels are not in the data file, then they must exist in the Mattermost database. -Post - Optional. If present, Post objects must occur after the last User object but before any DirectChannel objects. Each Post object defines the team, the channel, and the username of the user who posted the message. If the corresponding team, channel, or user are not in the data file, then they must exist in the Mattermost database. -DirectChannel - Optional. If present, DirectChannel objects must occur after all Post objects in the file and before any DirectPost objects. -DirectPost - Optional. If present, DirectPost objects must occur after all other objects in the file. Each DirectPost object defines the usernames of the channel members and the username of the user who posted the message. If the corresponding usernames are not in the data file, then they must exist in the Mattermost database. - -With the exception of the Version object, each object has a field or a combination of fields that is used as the unique identifier of that object. The bulk loader uses the unique identifier to determine if the object being imported is a new object or an update to an existing object. - -The identifiers for each object are listed in the following table: - -.. csv-table:: Objects and their unique identifiers - :header: Object, Unique Identifier - - Version, Not Applicable - Scheme, *name* - Role, *name* - Emoji, *name* - Team, *name* - Channel, "*name*, *team*" - User, *username* - UserNotifyProps, *username* - UserTeamMembership, "*team*, *username*" - UserChannelMembership, "*team*, *channel*, *username*" - Post, "*channel*, *message*, *create_at*" - Reply, "*post*, *message*, *create_at*" - Reaction, "*post*, *emoji_name*, *create_at*" - Attachment, "*path*" - DirectChannel, *members* - DirectPost, "*channel_members*, *user*, *message*, *create_at* " - -The following fragment is from a file that imports two teams, each with two channels, many users, and many posts. - -.. code-block:: javascript - :linenos: - - { "type": "version", ... } - { "type": "team", "team": { "name": "TeamA", ...} } - { "type": "team", "team": { "name": "TeamB", ...} } - { "type": "channel", "channel": { "team": "TeamA", "name": "channel_a1", ...} } - { "type": "channel", "channel": { "team": "TeamA", "name": "channel_a2", ...} } - { "type": "channel", "channel": { "team": "TeamB", "name": "channel_b1", ...} } - { "type": "channel", "channel": { "team": "TeamB", "name": "channel_b2", ...} } - { "type": "user", "user": { "username": "user001", ...} } - { "type": "user", "user": { "username": "user002", ...} } - { "type": "user", "user": { "username": "user003", ...} } - { "type": "user", ... } - { "type": "user", ... } - { "type": "user", ... } - . - . - . - { "type": "post", { "team": "TeamA", "name": "channel_a1", "user": "user001", ...} } - { "type": "post", { "team": "TeamA", "name": "channel_a1", "user": "user001", ...} } - { "type": "post", { "team": "TeamA", "name": "channel_a1", "user": "user001", ...} } - . - . - . - -Version object --------------- - -The Version object must be the first object in the data file, and can appear only once. The version represents the version of the bulk import tool and currently is ``1``. - -Example Version object -~~~~~~~~~~~~~~~~~~~~~~ - -For clarity, the object is shown using regular JSON formatting, but in the data file it cannot be spread across several lines. It must be all on one line. - -.. code-block:: javascript - - { - "type": "version", - "version": 1 - } - -Fields of the Version object -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - -
Field nameTypeDescriptionValidatedMandatory
typestringMust be the string "version"YesYes
versionnumberMust be the number 1.YesYes
- -Scheme object -------------- - -Scheme objects represent Permissions Schemes in the Mattermost permissions system. If present, Scheme objects must occur after the Version object and before any Team objects. - -Example Scheme object -~~~~~~~~~~~~~~~~~~~~~ - -For clarity, the object is shown using regular JSON formatting, but in the data file it cannot be spread across several lines. It must be all on one line. - -.. code-block:: javascript - - { - "type": "scheme", - "scheme": { - "name": "custom_scheme_name", - "display_name": "Custom Scheme Name", - "description": "This is a custom override scheme.", - "scope": "team", - "default_team_admin_role": { - "name": "custom_scheme_team_admin_role", - "display_name": "Custom Scheme Team Admin Role", - "description": "This is the default team admin role for the custom scheme.", - "permissions": ["add_user_to_team", "manage_team_roles"], - }, - "default_team_user_role": { - "name": "custom_scheme_team_user_role", - "display_name": "Custom Scheme Team User Role", - "description": "This is the default team user role for the custom scheme.", - "permissions": ["create_public_channel", "create_private_channel"], - }, - "default_channel_admin_role": { - "name": "custom_scheme_channel_admin_role", - "display_name": "Custom Scheme Channel Admin Role", - "description": "This is the default channel admin role for the custom scheme.", - "permissions": ["manage_private_channel_members", "manage_channel_roles"], - }, - "default_channel_user_role": { - "name": "custom_scheme_channel_user_role", - "display_name": "Custom Scheme Channel User Role", - "description": "This is the default channel user role for the custom scheme.", - "permissions": ["manage_public_channel_members", "manage_public_channel_properties"], - }, - } - } - -Fields of the Scheme object -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Field nameTypeDescriptionValidatedMandatory
namestringThe scheme name. Must start with and contain only lowercase letters ([a-z0-9]) or _, and must be between 2-64 characters in length.YesYes
display_namestringThe display name for the scheme.YesYes
scopestringThe scope for the scheme. Must be either "team" or "channel".YesYes
descriptionstringThe description of the scheme.YesNo
default_team_admin_roleRole objectThe default role applied to team admins in teams using this scheme. This field is mandatory if the scheme scope is set to "team", otherwise must not be present.YesNo
default_team_user_roleRole objectThe default role applied to Team Users in teams using this scheme. This field is mandatory if the scheme scope is set to "team", otherwise must not be present.YesNo
default_channel_admin_roleRole objectThe default role applied to channel admins in channels using this scheme. This field is mandatory for both "team" and "channel" scope schemes.YesYes
default_channel_user_roleRole objectThe default role applied to Channel Users in channels using this scheme. This field is mandatory for both "team" and "channel" scope schemes.YesYes
- -Fields of the Role object -~~~~~~~~~~~~~~~~~~~~~~~~~ - -This object is a member of the Scheme object. - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Field nameTypeDescriptionValidatedMandatory
namestringThe scheme name.YesYes
display_namestringThe display name for the scheme.YesYes
descriptionstringThe description of the scheme.YesNo
permissionsarrayThe permissions the role should grant. This is an array of strings where the strings are the names of individual permissions in the Mattermost permissions system.YesNo
- -Emoji object ------------- - -Emoji objects represent custom Emoji. If present, Emoji objects must occur after the Version object and before any Team objects. - -Example Emoji object -~~~~~~~~~~~~~~~~~~~~ - -For clarity, the object is shown using regular JSON formatting, but in the data file it cannot be spread across several lines. It must be all on one line. - -.. code-block:: javascript - - { - "type": "emoji", - "emoji": { - "name": "custom-emoji-troll", - "image": "bulkdata/emoji/trollolol.png" - } - } - -Fields of the Emoji object -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - -
Field nameTypeDescriptionValidatedMandatory
namestringThe emoji name.YesYes
imagestringThe path (either absolute or relative to the current working directory) to the image file for this emoji.NoYes
- -Team object ------------ - -If present, Team objects must occur after the Version object and before any Channel objects. - -Example Team object -~~~~~~~~~~~~~~~~~~~ - -For clarity, the object is shown using regular JSON formatting, but in the data file it cannot be spread across several lines. It must be all on one line. - -.. code-block:: javascript - - { - "type": "team", - "team": { - "name": "team-name", - "display_name": "Team Display Name", - "type": "O", - "description": "The Team Description", - "allow_open_invite": true - } - } - -Fields of the Team object -~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[1] Not validated, but an error occurs if no such scheme exists when running in apply mode.
Field nameTypeDescriptionValidatedMandatory
namestringThe team name.YesYes
display_namestringThe display name for the team.YesYes
typestringThe type of team. Can have one the following values:
- O for an open team
- I for an invite-only team.		YesYes
descriptionstringThe team description.YesNo
allow_open_inviteboolWhether to allow open invitations. Must have one of the following values:
- true
- false - 		YesNo
schemestringThe name of the Scheme that should be applied to this team.No [1]No
- -Channel object --------------- - -If present, Channel objects must occur after all Team objects and before any User objects. - -Example Channel object -~~~~~~~~~~~~~~~~~~~~~~ - -For clarity, the object is shown using regular JSON formatting, but in the data file it cannot be spread across several lines. It must be all on one line. - -.. code-block:: javascript - - { - "type": "channel", - "channel": { - "team": "team-name", - "name": "channel-name", - "display_name": "Channel Name", - "type": "O", - "header": "The Channel Header", - "purpose": "The Channel Purpose", - } - } - -Fields of the Channel object -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[1] Not validated, but an error occurs if no such team/scheme exists when running in apply mode.
Field nameTypeDescriptionValidatedMandatory
teamstringThe name of the team this channel belongs to.No [1]Yes
namestringThe name of the channel. Must start with and contain only lowercase letters ([a-z0-9]) or - or _.YesYes
display_namestringThe display name for the channel.Yesyes
typestringThe type of channel. Can have one the following values:
- O for a public channel.
- P for a private channel.		YesYes
headerstringThe channel header.YesNo
purposestringThe channel purpose.YesNo
schemestringThe name of the Scheme that should be applied to this team.No [1]No
- -User object ------------ - -If present, User objects must occur after the Team and Channel objects in the file and before any Post objects. - -Example User object -~~~~~~~~~~~~~~~~~~~ - -For clarity, the object is shown using regular JSON formatting, but in the data file it cannot be spread across several lines. It must be all on one line. - -.. code-block:: javascript - - { - "type": "user", - "user": { - "profile_image": "profile-picture.png", - "username": "username", - "email": "email@example.com", - "auth_service": "", - "password": "passw0rd", - "nickname": "bobuser", - "first_name": "Bob", - "last_name": "User", - "position": "Senior Developer", - "roles": "system_user", - "locale": "pt_BR", - "teams": [ - { - "name": "team-name", - "theme": "{ - \"awayIndicator\":\"#DBBD4E\", - \"buttonBg\":\"#23A1FF\", - \"buttonColor\":\"#FFFFFF\", - \"centerChannelBg\":\"#ffffff\", - \"centerChannelColor\":\"#333333\", - \"codeTheme\":\"github\", - \"linkColor\":\"#2389d7\", - \"mentionBg\":\"#2389d7\", - \"mentionColor\":\"#ffffff\", - \"mentionHighlightBg\":\"#fff2bb\", - \"mentionHighlightLink\":\"#2f81b7\", - \"newMessageSeparator\":\"#FF8800\", - \"onlineIndicator\":\"#7DBE00\", - \"sidebarBg\":\"#fafafa\", - \"sidebarHeaderBg\":\"#3481B9\", - \"sidebarHeaderTextColor\":\"#ffffff\", - \"sidebarText\":\"#333333\", - \"sidebarTextActiveBorder\":\"#378FD2\", - \"sidebarTextActiveColor\":\"#111111\", - \"sidebarTextHoverBg\":\"#e6f2fa\", - \"sidebarUnreadText\":\"#333333\", - }", - "roles": "team_user team_admin", - "channels": [ - { - "name": "channel-name", - "roles": "channel_user", - "notify_props": { - "desktop": "default", - "mark_unread": "all" - } - } - ] - } - ] - } - } - -Fields of the User object -~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Field nameTypeDescriptionValidatedMandatory
profile_imagestringThe user’s profile image. This must be an existing file path.YesNo
usernamestringThe user’s username. This is the unique identifier for the user.YesYes
emailstringThe user’s email address.YesYes
auth_servicestringThe authentication service to use for this user account. If not provided, it defaults to password-based authentication. Must be one of the following values:
- "" or not provided - password authentication.
- "gitlab" - GitLab authentication.
- "ldap" - LDAP authentication (Enterprise and Professional)
- "saml" - Generic SAML based authentication (Enterprise)
- "google" - Google OAuth authentication (Enterprise)
- "entra id" - Microsoft Entra ID OAuth Authentication (Enterprise)		NoNo
auth_datastringThe authentication data if auth_service is used. The value depends on the auth_service that is specified.
- The data comes from the following fields for the respective auth_services:
- "" or not provided - must be omitted.
- "gitlab" - The value of the Id attribute provided in the GitLab auth data.
- "ldap" - The value of the LDAP attribute specified as the "ID Attribute" in the Mattermost LDAP configuration.
- "saml" - The value of the SAML Email address attribute.
- "google" - The value of the OAuth Id attribute.
- "office365" - The value of the OAuth Id attribute.		NoNo
passwordstringA password for the user. Can be present only when password-based authentication is used. When password-based authentication is used and the password is not present, the bulk loader generates a password.YesNo
nicknamestringThe user’s nickname.YesNo
first_namestringThe user’s first name.YesNo
last_namestringThe user’s last name.YesNo
positionstringThe user’s position.YesNo
rolesstringThe user’s roles. Must be one of the following values:
- "system_user"
- "system_admin system_user"		YesNo
localestringThe user’s locale. This must be a valid locale for which Mattermost has been localised.NoNo
delete_atint64Timestamp for when the user was deactivated.NoNo
teamsarrayThe teams which the user will be made a member of. Must be an array of UserTeamMembership objects.YesNo
themestringThe user’s theme. Formatted as a Mattermost theme string.NoNo
military_timestringHow times should be displayed to this user. Must be one of the following values:
- "true" - Use 24 hour clock.
- "false" - Use 12 hour clock.		NoNo
collapse_previewsstringWhether to collapse or expand link previews by default. Must be one of the following values:
- "true" - Collapsed by default.
- "false" - Expanded by default.		NoNo
message_displaystringWhich style to use for displayed messages. Must be one of the following values:
- "clean" - Use the standard style.
- "compact" - Use the compact style.		NoNo
channel_display_modestringHow to display channel messages. Must be one of the following values:
- "full" - Use the full width of the screen.
- "centered" - Use a fixed width, centered block.		NoNo
tutorial_stepstringWhere to start the user tutorial. Must be one of the following values:
- "1", "2" or "3" - Start from the specified tutorial step.
- "999" - Skip the user tutorial.		NoNo
use_markdown_previewboolEnable preview of message markdown formatting. Can have one the following values:
- "True"
- "False" 		YesYes
use_formattingboolEnable post formatting for links, emoji, text styles and line breaks. Can have one the following values:
- "True"
- "False" 		YesYes
show_unread_sectionboolEnable showing unread messages at top of channel sidebar. Can have one the following values:
- "True"
- "False" 		YesYes
email_intervalstringSpecify an email batching interval during bulk import. Can have one of the following values:
- "immediate" - Emails are sent immediately.
- "fifteen" - Emails are batched and sent every 15 minutes.
- "hour" - Emails are batched and sent every hour.
YesYes
notify_propsUserNotifyProps objectThe user’s notify preferences, as defined by the UserNotifyProps object.YesNo
- -Fields of the UserNotifyProps object -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This object is a member of the User object. - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[1] Not validated, but an error occurs if no such team exists when running in apply mode.
Field nameTypeDescriptionValidatedMandatory
desktopstringPreference for sending desktop notifications. Must be one of the following values:
- "all" - For all activity.
- "mention" - Only for mentions.
- "none" - Never.		YesNo
desktop_soundstringPreference for whether desktop notification sound is played. Must be one of the following values:
- "true" - Sound is played.
- "false" - Sound is not played.		YesNo
emailstringPreference for email notifications. Must be one of the following values:
- "true" - Email notifications are sent based on the email_interval setting
- "false" - Email notifications are not sent.		NoNo
mobilestringPreference for sending mobile push notifications. Must be one of the following values:
- "all" - For all activity.
- "mention" - Only for mentions.
- "none" - Never.		YesNo
mobile_push_statusstringPreference for when push notifications are triggered. Must be one of the following values:
- "online" - When online, away or offline.
- "away" - When away or offline.
- "offline" - When offline.		YesNo
channelstringWhether @all, @channel and @here trigger mentions. Must be one of the following values:
- "true" - Mentions are triggered.
- "false" - Mentions are not triggered.		YesNo
commentsstringPreference for reply mention notifications. Must be one of the following values:
- "any" - Trigger notifications on messages in reply threads that the user starts or participates in.
- "root" - Trigger notifications on messages in threads that the user starts.
- "never" - Do not trigger notifications on messages in reply threads unless the user is mentioned.		YesNo
mention_keysstringPreference for custom non-case sensitive words that trigger mentions. Words must be separated by commas.NoNo
- -Fields of the UserTeamMembership object -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This object is a member of the User object. - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[1] Not validated, but an error occurs if no such team exists when running in apply mode.
Field nameTypeDescriptionValidatedMandatory
namestringThe name of the team this user should be a member of.No [1]Yes
themestringThe user’s theme for the specified team. Formatted as a Mattermost theme string.YesNo
rolesstringThe roles the user should have within this team. Must be one of the following values:
- "team_user"
- "team_admin team_user" - 		YesNo
channelsarrayThe channels within this team that the user should be made a member of. Must be an array of UserChannelMembership objects.YesNo
- -Fields of the UserChannelMembership object -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This object is a member of the TeamMembership object. - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[1] Not validated, but an error occurs if the parent channel does not exist when running in apply mode.
Field nameTypeDescriptionValidatedMandatory
namestringThe name of the channel in the parent team that this user should be a member of.No [1]Yes
rolesstringThe roles the user should have within this channel. Must be one of the following values:
- "channel_user"
- "channel_user channel_admin" - 		YesNo
notify_propsobjectThe notify preferences for this user in this channel. Must be a ChannelNotifyProps objectYesNo
favoritebooleanWhether to favorite the channel. Must be one of the following values:
- "true" - Yes.
- "false" - No.		NoNo
- -Fields of the ChannelNotifyProps object -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This object is a member of the ChannelMembership object. - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Field nameTypeDescriptionValidatedMandatory
desktopstringPreference for sending desktop notifications. Must be one of the following values:
- "default" - Global default.
- "all" - For all activity.
- "mention" - Only for mentions.
- "none" - Never.		YesNo
mobilestringPreference for sending mobile notifications. Must be one of the following values:
- "default" - Global default.
- "all" - For all activity.
- "mention" - Only for mentions.
- "none" - Never.		YesNo
mark_unreadstringPreference for marking channel as unread. Must be one of the following values:
- "all" - For all unread messages.
- "mention" - Only for mentions. - 		YesNo
- -Post object ------------ - -If present, Post objects must occur after the last User object in the file, but before any DirectChannel objects. - -Example Post object -~~~~~~~~~~~~~~~~~~~ - -For clarity, the object is shown using regular JSON formatting, but in the data file it cannot be spread across several lines. It must be all on one line. - -.. code-block:: javascript - - { - "type": "post", - "post": { - "team": "team-name", - "channel": "channel-name", - "user": "username", - "message": "The post message", - "props": { - "attachments": [{ - "pretext": "This is the attachment pretext.", - "text": "This is the attachment text." - }] - }, - "create_at": 140012340013, - "flagged_by": [ - "username1", - "username2", - "username3" - ], - "replies": [{ - "user": "username4", - "message": "The reply message", - "create_at": 140012352049, - "attachments": [{ - "path": "/some/valid/file/path/1" - }], - }, { - "user": "username5", - "message": "Other reply message", - "create_at": 140012353057, - }], - "reactions": [{ - "user": "username6", - "emoji_name": "+1", - "create_at": 140012356032, - }, { - "user": "username7", - "emoji_name": "heart", - "create_at": 140012359034, - }], - "attachments": [{ - "path": "/some/valid/file/path/1" - }, { - "path": "/some/valid/file/path/2" - }] - } - } - - -Fields of the Post object -~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[1] Not validated, but an error occurs if the team does not exist when running in apply mode.
- [2] Not validated, but an error occurs if the channel does not exist in the corresponding team when running in apply mode.
- [3] Not validated, but an error occurs if the user does not exist when running in apply mode. -
Field nameTypeDescriptionValidatedMandatory
teamstringThe name of the team that this post is in.No [1]Yes
channelstringThe name of the channel that this post is in.No [2]Yes
userstringThe username of the user for this post.No [3]Yes
messagestringThe message that the post contains.YesYes
propsobjectThe props for a post. Contains additional formatting information used by integrations and bot posts. For a more detailed explanation see the message attachments documentation.YesYes
create_atintThe timestamp for the post, in milliseconds since the Unix epoch.YesYes
flagged_byarrayMust contain a list of members who have flagged the post.NoNo
repliesarrayThe posts in reply to this post. Must be an array of Reply objects.YesNo
reactionsarrayThe emoji reactions to this post. Must be an array of Reaction objects.YesNo
attachmentsarrayFile attachments associated with this post. Must be an array of Attachment objects.YesNo
- -Fields of the Reply object -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This object is a member of the Post/DirectPost object. - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Field nameTypeDescriptionValidatedMandatory
userstringThe username of the user for this reply.No [3]Yes
messagestringThe message that the reply contains.YesYes
create_atintThe timestamp for the reply, in milliseconds since the Unix epoch.YesYes
flagged_byarrayMust contain a list of members who have flagged the post.NoNo
reactionsarrayThe emoji reactions to this post. Must be an array of Reaction objects.YesNo
attachmentsarrayThe file attachments to this post. Must be an array of Attachment objects.YesNo
- -Fields of the Reaction object -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This object is a member of the Post/DirectPost object. - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Field nameTypeDescriptionValidatedMandatory
userstringThe username of the user for this reply.No [3]Yes
emoji_namestringThe emoji of the reaction.YesYes
create_atintThe timestamp for the reply, in milliseconds since the Unix epoch.YesYes
- -Fields of the Attachment object -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This object is a member of the Post/DirectPost object. - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - -
- [1] Not validated, but an error occurs if the file path is not found or accessible when running in apply mode. -
Field nameTypeDescriptionValidatedMandatory
pathstringThe path to the file to be attached to the post.No [1]Yes
- -DirectChannel object --------------------- - -A direct channel can have from two to eight users as members of the channel. If there are only two members, Mattermost treats it as a Direct Message channel. If there are three or more members, Mattermost treats it as a Group Message channel. - -Example DirectChannel object -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -For clarity, the object is shown using regular JSON formatting, but in the data file it cannot be spread across several lines. It must be all on one line. - -.. code-block:: javascript - - { - "type": "direct_channel", - "direct_channel": { - "members": [ - "username1", - "username2", - "username3" - ], - "header": "The Channel Header", - "favorited_by": [ - "username1", - "username2", - "username3" - ] - } - } - -Fields of the DirectChannel object -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[1] Not validated, but an error occurs if one or more of the users don't exist when running in apply mode. -
Field nameTypeDescriptionValidatedMandatory
membersarrayMust contain a list of members, with a minimum of two usernames and a maximum of eight usernames.No [1]Yes
headerstringThe channel header.YesNo
favorited_byarrayMust contain a list of members who have favorited the channel.NoNo
- -DirectPost object ------------------ - -DirectPost objects must occur after all other objects in the file. - -Example DirectPost object -~~~~~~~~~~~~~~~~~~~~~~~~~ - -For clarity, the object is shown using regular JSON formatting, but in the data file it cannot be spread across several lines. It must be all on one line. - -.. code-block:: javascript - - { - "type": "direct_post", - "direct_post": { - "channel_members": [ - "username1", - "username2", - "username3", - ], - "user": "username2", - "message": "Hello Group Channel", - "create_at": 140012340013, - "flagged_by": [ - "username1", - "username2", - "username3" - ], - "replies": [{ - "user": "username4", - "message": "The reply message", - "create_at": 140012352049, - }, { - "user": "username5", - "message": "Other reply message", - "create_at": 140012353057, - }], - "reactions": [{ - "user": "username6", - "emoji_name": "+1", - "create_at": 140012356032, - }, { - "user": "username7", - "emoji_name": "heart", - "create_at": 140012359034, - }] - } - } - -Fields of the DirectPost object -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
[1] Not validated, but an error occurs if no channels contain an identical list when running in apply mode.
[2] Not validated, but an error occurs if the user does not exist when running in apply mode. -
Field nameTypeDescriptionValidatedMandatory
channel_membersarrayMust contain a list of members, with a minimum of two usernames and a maximum of eight usernames.No [1]Yes
userstringThe username of the user for this post.No [2]Yes
messagestringThe message that the post contains.YesYes
create_atintThe timestamp for the post, in milliseconds since the Unix epoch.YesYes
flagged_byarrayMust contain a list of members who have flagged the post.NoNo
repliesarrayThe posts in reply to this direct post. Must be an array of Reply objects.YesNo
reactionsarrayThe emoji reactions to this direct post. Must be an array of Reaction objects.YesNo
attachmentsarrayThe attachments to this direct post. Must be an array of Attachment objects.YesNo
diff --git a/source/onboard/bulk-loading-data.rst b/source/onboard/bulk-loading-data.rst index 1f2327320b5..36fd4904e2a 100644 --- a/source/onboard/bulk-loading-data.rst +++ b/source/onboard/bulk-loading-data.rst @@ -29,17 +29,1590 @@ You can import the following data types: Importing additional types of posts is not yet supported. -.. include:: bulk-loading-about.rst - :start-after: :nosearch: +About the bulk loading command +------------------------------ -.. include:: run-bulk-loading-command.rst - :start-after: :nosearch: +**The bulk loading command is interruptible and idempotent** -.. include:: bulk-loading-data-format.rst - :start-after: :nosearch: +If the import is interrupted for any reason, it continues from where it left off the next time you run it. You can run the command repeatedly with the same data file, and the data is imported only once. Posts with matching timestamps to incoming posts will have their attachments replaced by the incoming data. Prior to v5.20 any updates to posts with matching timestamps were appended to older posts. -.. include:: bulk-loading-common-issues.rst - :start-after: :nosearch: +**You can run the bulk loading command on a live system** -.. include:: bulk-loading-troubleshooting.rst - :start-after: :nosearch: +Although you don't need to shut down Mattermost to run the command, changes made by users of the system between runs can be overwritten if the corresponding fields exist in the data file. + +**Some data fields are optional** + +Not all fields are mandatory. If an optional field is missing from the object that is being imported, the field's current value in the database is not changed. + +**The bulk loading command is not a synchronization tool** + +You cannot use the bulk loading command to remove any objects or their fields from the Mattermost database. The command only creates or overwrites fields. + +.. important:: + The bulk loading command runs in the mmctl and operates in the security context of the mmctl. This means it has full permissions to access and alter everything in the Mattermost database. + +Bulk load data +--------------- + +Before running the bulk loading command, you must first create a `JSONL `__ file that contains the data that you want to import in your Mattermost directory. The file can have any name, but in this example it's called ``data.jsonl``. The format of the file is described in the :ref:`data-format ` section. + +Next, zip it by running the ``zip -r data.zip data.jsonl`` command. + +Using mmctl local mode +~~~~~~~~~~~~~~~~~~~~~~ + +From Mattermost v9.5, the mmctl bulk import process command in :ref:`local mode ` supports processing an import file without uploading it to the server. + +Run ``mmctl import process --bypass-upload .zip --local`` to start your import and enable the Mattermost server to read from the file directly. + +Not using mmctl local mode +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you're not running mmctl commands in local mode: + +1. Upload the ZIP file to the database by running the :ref:`mmctl import upload ` command. For example: ``mmctl import upload data.zip``. +2. Confirm that the file is uploaded and ready for use by running the :ref:`mmctl import list available ` command. +3. Import your uploaded file by running the :ref:`mmctl import process ` command. For example: ``mmctl import process _data.zip`` (use the name of the uploaded file from :ref:`mmctl import list available ` command). + +Data format +----------- + +The input data file must be a valid `JSONL `__ file with the following objects, each on its own line in the file. The objects must occur in the file in the order listed. + +Version + Mandatory. The Version object must be the first line in the file, and must occur only once. The version is the version of the bulk importer tool, which is currently ``1``. +Scheme + Optional. If present, Scheme objects must occur after the Version object but before any Team objects. +Emoji + Optional. If present, Emoji objects must occur after the Version objects but before any Team objects. +Team + Optional. If present, Team objects must occur after any Scheme objects and before any Channel objects. +Channel + Optional. If present, Channel objects must occur after all Team objects and before any User objects. +User + Optional. If present, User objects must occur after the Team and Channel objects in the file and before any Post objects. Each User object defines the teams and channels that the user is a member of. If the corresponding teams and channels are not in the data file, then they must exist in the Mattermost database. +Post + Optional. If present, Post objects must occur after the last User object but before any DirectChannel objects. Each Post object defines the team, the channel, and the username of the user who posted the message. If the corresponding team, channel, or user are not in the data file, then they must exist in the Mattermost database. +DirectChannel + Optional. If present, DirectChannel objects must occur after all Post objects in the file and before any DirectPost objects. +DirectPost + Optional. If present, DirectPost objects must occur after all other objects in the file. Each DirectPost object defines the usernames of the channel members and the username of the user who posted the message. If the corresponding usernames are not in the data file, then they must exist in the Mattermost database. + +With the exception of the Version object, each object has a field or a combination of fields that is used as the unique identifier of that object. The bulk loader uses the unique identifier to determine if the object being imported is a new object or an update to an existing object. + +The identifiers for each object are listed in the following table: + +.. csv-table:: Objects and their unique identifiers + :header: Object, Unique Identifier + + Version, Not Applicable + Scheme, *name* + Role, *name* + Emoji, *name* + Team, *name* + Channel, "*name*, *team*" + User, *username* + UserNotifyProps, *username* + UserTeamMembership, "*team*, *username*" + UserChannelMembership, "*team*, *channel*, *username*" + Post, "*channel*, *message*, *create_at*" + Reply, "*post*, *message*, *create_at*" + Reaction, "*post*, *emoji_name*, *create_at*" + Attachment, "*path*" + DirectChannel, *members* + DirectPost, "*channel_members*, *user*, *message*, *create_at* " + +The following fragment is from a file that imports two teams, each with two channels, many users, and many posts. + +.. code-block:: javascript + :linenos: + + { "type": "version", ... } + { "type": "team", "team": { "name": "TeamA", ...} } + { "type": "team", "team": { "name": "TeamB", ...} } + { "type": "channel", "channel": { "team": "TeamA", "name": "channel_a1", ...} } + { "type": "channel", "channel": { "team": "TeamA", "name": "channel_a2", ...} } + { "type": "channel", "channel": { "team": "TeamB", "name": "channel_b1", ...} } + { "type": "channel", "channel": { "team": "TeamB", "name": "channel_b2", ...} } + { "type": "user", "user": { "username": "user001", ...} } + { "type": "user", "user": { "username": "user002", ...} } + { "type": "user", "user": { "username": "user003", ...} } + { "type": "user", ... } + { "type": "user", ... } + { "type": "user", ... } + . + . + . + { "type": "post", { "team": "TeamA", "name": "channel_a1", "user": "user001", ...} } + { "type": "post", { "team": "TeamA", "name": "channel_a1", "user": "user001", ...} } + { "type": "post", { "team": "TeamA", "name": "channel_a1", "user": "user001", ...} } + . + . + . + +Version object +-------------- + +The Version object must be the first object in the data file, and can appear only once. The version represents the version of the bulk import tool and currently is ``1``. + +Example Version object +~~~~~~~~~~~~~~~~~~~~~~ + +For clarity, the object is shown using regular JSON formatting, but in the data file it cannot be spread across several lines. It must be all on one line. + +.. code-block:: javascript + + { + "type": "version", + "version": 1 + } + +Fields of the Version object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + +
Field nameTypeDescriptionValidatedMandatory
typestringMust be the string "version"YesYes
versionnumberMust be the number 1.YesYes
+ +Scheme object +------------- + +Scheme objects represent Permissions Schemes in the Mattermost permissions system. If present, Scheme objects must occur after the Version object and before any Team objects. + +Example Scheme object +~~~~~~~~~~~~~~~~~~~~~ + +For clarity, the object is shown using regular JSON formatting, but in the data file it cannot be spread across several lines. It must be all on one line. + +.. code-block:: javascript + + { + "type": "scheme", + "scheme": { + "name": "custom_scheme_name", + "display_name": "Custom Scheme Name", + "description": "This is a custom override scheme.", + "scope": "team", + "default_team_admin_role": { + "name": "custom_scheme_team_admin_role", + "display_name": "Custom Scheme Team Admin Role", + "description": "This is the default team admin role for the custom scheme.", + "permissions": ["add_user_to_team", "manage_team_roles"], + }, + "default_team_user_role": { + "name": "custom_scheme_team_user_role", + "display_name": "Custom Scheme Team User Role", + "description": "This is the default team user role for the custom scheme.", + "permissions": ["create_public_channel", "create_private_channel"], + }, + "default_channel_admin_role": { + "name": "custom_scheme_channel_admin_role", + "display_name": "Custom Scheme Channel Admin Role", + "description": "This is the default channel admin role for the custom scheme.", + "permissions": ["manage_private_channel_members", "manage_channel_roles"], + }, + "default_channel_user_role": { + "name": "custom_scheme_channel_user_role", + "display_name": "Custom Scheme Channel User Role", + "description": "This is the default channel user role for the custom scheme.", + "permissions": ["manage_public_channel_members", "manage_public_channel_properties"], + }, + } + } + +Fields of the Scheme object +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field nameTypeDescriptionValidatedMandatory
namestringThe scheme name. Must start with and contain only lowercase letters ([a-z0-9]) or _, and must be between 2-64 characters in length.YesYes
display_namestringThe display name for the scheme.YesYes
scopestringThe scope for the scheme. Must be either "team" or "channel".YesYes
descriptionstringThe description of the scheme.YesNo
default_team_admin_roleRole objectThe default role applied to team admins in teams using this scheme. This field is mandatory if the scheme scope is set to "team", otherwise must not be present.YesNo
default_team_user_roleRole objectThe default role applied to Team Users in teams using this scheme. This field is mandatory if the scheme scope is set to "team", otherwise must not be present.YesNo
default_channel_admin_roleRole objectThe default role applied to channel admins in channels using this scheme. This field is mandatory for both "team" and "channel" scope schemes.YesYes
default_channel_user_roleRole objectThe default role applied to Channel Users in channels using this scheme. This field is mandatory for both "team" and "channel" scope schemes.YesYes
+ +Fields of the Role object +~~~~~~~~~~~~~~~~~~~~~~~~~ + +This object is a member of the Scheme object. + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field nameTypeDescriptionValidatedMandatory
namestringThe scheme name.YesYes
display_namestringThe display name for the scheme.YesYes
descriptionstringThe description of the scheme.YesNo
permissionsarrayThe permissions the role should grant. This is an array of strings where the strings are the names of individual permissions in the Mattermost permissions system.YesNo
+ +Emoji object +------------ + +Emoji objects represent custom Emoji. If present, Emoji objects must occur after the Version object and before any Team objects. + +Example Emoji object +~~~~~~~~~~~~~~~~~~~~ + +For clarity, the object is shown using regular JSON formatting, but in the data file it cannot be spread across several lines. It must be all on one line. + +.. code-block:: javascript + + { + "type": "emoji", + "emoji": { + "name": "custom-emoji-troll", + "image": "bulkdata/emoji/trollolol.png" + } + } + +Fields of the Emoji object +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + +
Field nameTypeDescriptionValidatedMandatory
namestringThe emoji name.YesYes
imagestringThe path (either absolute or relative to the current working directory) to the image file for this emoji.NoYes
+ +Team object +----------- + +If present, Team objects must occur after the Version object and before any Channel objects. + +Example Team object +~~~~~~~~~~~~~~~~~~~ + +For clarity, the object is shown using regular JSON formatting, but in the data file it cannot be spread across several lines. It must be all on one line. + +.. code-block:: javascript + + { + "type": "team", + "team": { + "name": "team-name", + "display_name": "Team Display Name", + "type": "O", + "description": "The Team Description", + "allow_open_invite": true + } + } + +Fields of the Team object +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[1] Not validated, but an error occurs if no such scheme exists when running in apply mode.
Field nameTypeDescriptionValidatedMandatory
namestringThe team name.YesYes
display_namestringThe display name for the team.YesYes
typestringThe type of team. Can have one the following values:
+ O for an open team
+ I for an invite-only team.		YesYes
descriptionstringThe team description.YesNo
allow_open_inviteboolWhether to allow open invitations. Must have one of the following values:
+ true
+ false + 		YesNo
schemestringThe name of the Scheme that should be applied to this team.No [1]No
+ +Channel object +-------------- + +If present, Channel objects must occur after all Team objects and before any User objects. + +Example Channel object +~~~~~~~~~~~~~~~~~~~~~~ + +For clarity, the object is shown using regular JSON formatting, but in the data file it cannot be spread across several lines. It must be all on one line. + +.. code-block:: javascript + + { + "type": "channel", + "channel": { + "team": "team-name", + "name": "channel-name", + "display_name": "Channel Name", + "type": "O", + "header": "The Channel Header", + "purpose": "The Channel Purpose", + } + } + +Fields of the Channel object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[1] Not validated, but an error occurs if no such team/scheme exists when running in apply mode.
Field nameTypeDescriptionValidatedMandatory
teamstringThe name of the team this channel belongs to.No [1]Yes
namestringThe name of the channel. Must start with and contain only lowercase letters ([a-z0-9]) or - or _.YesYes
display_namestringThe display name for the channel.Yesyes
typestringThe type of channel. Can have one the following values:
+ O for a public channel.
+ P for a private channel.		YesYes
headerstringThe channel header.YesNo
purposestringThe channel purpose.YesNo
schemestringThe name of the Scheme that should be applied to this team.No [1]No
+ +User object +----------- + +If present, User objects must occur after the Team and Channel objects in the file and before any Post objects. + +Example User object +~~~~~~~~~~~~~~~~~~~ + +For clarity, the object is shown using regular JSON formatting, but in the data file it cannot be spread across several lines. It must be all on one line. + +.. code-block:: javascript + + { + "type": "user", + "user": { + "profile_image": "profile-picture.png", + "username": "username", + "email": "email@example.com", + "auth_service": "", + "password": "passw0rd", + "nickname": "bobuser", + "first_name": "Bob", + "last_name": "User", + "position": "Senior Developer", + "roles": "system_user", + "locale": "pt_BR", + "teams": [ + { + "name": "team-name", + "theme": "{ + \"awayIndicator\":\"#DBBD4E\", + \"buttonBg\":\"#23A1FF\", + \"buttonColor\":\"#FFFFFF\", + \"centerChannelBg\":\"#ffffff\", + \"centerChannelColor\":\"#333333\", + \"codeTheme\":\"github\", + \"linkColor\":\"#2389d7\", + \"mentionBg\":\"#2389d7\", + \"mentionColor\":\"#ffffff\", + \"mentionHighlightBg\":\"#fff2bb\", + \"mentionHighlightLink\":\"#2f81b7\", + \"newMessageSeparator\":\"#FF8800\", + \"onlineIndicator\":\"#7DBE00\", + \"sidebarBg\":\"#fafafa\", + \"sidebarHeaderBg\":\"#3481B9\", + \"sidebarHeaderTextColor\":\"#ffffff\", + \"sidebarText\":\"#333333\", + \"sidebarTextActiveBorder\":\"#378FD2\", + \"sidebarTextActiveColor\":\"#111111\", + \"sidebarTextHoverBg\":\"#e6f2fa\", + \"sidebarUnreadText\":\"#333333\", + }", + "roles": "team_user team_admin", + "channels": [ + { + "name": "channel-name", + "roles": "channel_user", + "notify_props": { + "desktop": "default", + "mark_unread": "all" + } + } + ] + } + ] + } + } + +Fields of the User object +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field nameTypeDescriptionValidatedMandatory
profile_imagestringThe user’s profile image. This must be an existing file path.YesNo
usernamestringThe user’s username. This is the unique identifier for the user.YesYes
emailstringThe user’s email address.YesYes
auth_servicestringThe authentication service to use for this user account. If not provided, it defaults to password-based authentication. Must be one of the following values:
+ "" or not provided - password authentication.
+ "gitlab" - GitLab authentication.
+ "ldap" - LDAP authentication (Enterprise and Professional)
+ "saml" - Generic SAML based authentication (Enterprise)
+ "google" - Google OAuth authentication (Enterprise)
+ "entra id" - Microsoft Entra ID OAuth Authentication (Enterprise)		NoNo
auth_datastringThe authentication data if auth_service is used. The value depends on the auth_service that is specified.
+ The data comes from the following fields for the respective auth_services:
+ "" or not provided - must be omitted.
+ "gitlab" - The value of the Id attribute provided in the GitLab auth data.
+ "ldap" - The value of the LDAP attribute specified as the "ID Attribute" in the Mattermost LDAP configuration.
+ "saml" - The value of the SAML Email address attribute.
+ "google" - The value of the OAuth Id attribute.
+ "office365" - The value of the OAuth Id attribute.		NoNo
passwordstringA password for the user. Can be present only when password-based authentication is used. When password-based authentication is used and the password is not present, the bulk loader generates a password.YesNo
nicknamestringThe user’s nickname.YesNo
first_namestringThe user’s first name.YesNo
last_namestringThe user’s last name.YesNo
positionstringThe user’s position.YesNo
rolesstringThe user’s roles. Must be one of the following values:
+ "system_user"
+ "system_admin system_user"		YesNo
localestringThe user’s locale. This must be a valid locale for which Mattermost has been localised.NoNo
delete_atint64Timestamp for when the user was deactivated.NoNo
teamsarrayThe teams which the user will be made a member of. Must be an array of UserTeamMembership objects.YesNo
themestringThe user’s theme. Formatted as a Mattermost theme string.NoNo
military_timestringHow times should be displayed to this user. Must be one of the following values:
+ "true" - Use 24 hour clock.
+ "false" - Use 12 hour clock.		NoNo
collapse_previewsstringWhether to collapse or expand link previews by default. Must be one of the following values:
+ "true" - Collapsed by default.
+ "false" - Expanded by default.		NoNo
message_displaystringWhich style to use for displayed messages. Must be one of the following values:
+ "clean" - Use the standard style.
+ "compact" - Use the compact style.		NoNo
channel_display_modestringHow to display channel messages. Must be one of the following values:
+ "full" - Use the full width of the screen.
+ "centered" - Use a fixed width, centered block.		NoNo
tutorial_stepstringWhere to start the user tutorial. Must be one of the following values:
+ "1", "2" or "3" - Start from the specified tutorial step.
+ "999" - Skip the user tutorial.		NoNo
use_markdown_previewboolEnable preview of message markdown formatting. Can have one the following values:
+ "True"
+ "False" 		YesYes
use_formattingboolEnable post formatting for links, emoji, text styles and line breaks. Can have one the following values:
+ "True"
+ "False" 		YesYes
show_unread_sectionboolEnable showing unread messages at top of channel sidebar. Can have one the following values:
+ "True"
+ "False" 		YesYes
email_intervalstringSpecify an email batching interval during bulk import. Can have one of the following values:
+ "immediate" - Emails are sent immediately.
+ "fifteen" - Emails are batched and sent every 15 minutes.
+ "hour" - Emails are batched and sent every hour.
YesYes
notify_propsUserNotifyProps objectThe user’s notify preferences, as defined by the UserNotifyProps object.YesNo
+ +Fields of the UserNotifyProps object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This object is a member of the User object. + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[1] Not validated, but an error occurs if no such team exists when running in apply mode.
Field nameTypeDescriptionValidatedMandatory
desktopstringPreference for sending desktop notifications. Must be one of the following values:
+ "all" - For all activity.
+ "mention" - Only for mentions.
+ "none" - Never.		YesNo
desktop_soundstringPreference for whether desktop notification sound is played. Must be one of the following values:
+ "true" - Sound is played.
+ "false" - Sound is not played.		YesNo
emailstringPreference for email notifications. Must be one of the following values:
+ "true" - Email notifications are sent based on the email_interval setting
+ "false" - Email notifications are not sent.		NoNo
mobilestringPreference for sending mobile push notifications. Must be one of the following values:
+ "all" - For all activity.
+ "mention" - Only for mentions.
+ "none" - Never.		YesNo
mobile_push_statusstringPreference for when push notifications are triggered. Must be one of the following values:
+ "online" - When online, away or offline.
+ "away" - When away or offline.
+ "offline" - When offline.		YesNo
channelstringWhether @all, @channel and @here trigger mentions. Must be one of the following values:
+ "true" - Mentions are triggered.
+ "false" - Mentions are not triggered.		YesNo
commentsstringPreference for reply mention notifications. Must be one of the following values:
+ "any" - Trigger notifications on messages in reply threads that the user starts or participates in.
+ "root" - Trigger notifications on messages in threads that the user starts.
+ "never" - Do not trigger notifications on messages in reply threads unless the user is mentioned.		YesNo
mention_keysstringPreference for custom non-case sensitive words that trigger mentions. Words must be separated by commas.NoNo
+ +Fields of the UserTeamMembership object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This object is a member of the User object. + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[1] Not validated, but an error occurs if no such team exists when running in apply mode.
Field nameTypeDescriptionValidatedMandatory
namestringThe name of the team this user should be a member of.No [1]Yes
themestringThe user’s theme for the specified team. Formatted as a Mattermost theme string.YesNo
rolesstringThe roles the user should have within this team. Must be one of the following values:
+ "team_user"
+ "team_admin team_user" + 		YesNo
channelsarrayThe channels within this team that the user should be made a member of. Must be an array of UserChannelMembership objects.YesNo
+ +Fields of the UserChannelMembership object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This object is a member of the TeamMembership object. + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[1] Not validated, but an error occurs if the parent channel does not exist when running in apply mode.
Field nameTypeDescriptionValidatedMandatory
namestringThe name of the channel in the parent team that this user should be a member of.No [1]Yes
rolesstringThe roles the user should have within this channel. Must be one of the following values:
+ "channel_user"
+ "channel_user channel_admin" + 		YesNo
notify_propsobjectThe notify preferences for this user in this channel. Must be a ChannelNotifyProps objectYesNo
favoritebooleanWhether to favorite the channel. Must be one of the following values:
+ "true" - Yes.
+ "false" - No.		NoNo
+ +Fields of the ChannelNotifyProps object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This object is a member of the ChannelMembership object. + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field nameTypeDescriptionValidatedMandatory
desktopstringPreference for sending desktop notifications. Must be one of the following values:
+ "default" - Global default.
+ "all" - For all activity.
+ "mention" - Only for mentions.
+ "none" - Never.		YesNo
mobilestringPreference for sending mobile notifications. Must be one of the following values:
+ "default" - Global default.
+ "all" - For all activity.
+ "mention" - Only for mentions.
+ "none" - Never.		YesNo
mark_unreadstringPreference for marking channel as unread. Must be one of the following values:
+ "all" - For all unread messages.
+ "mention" - Only for mentions. + 		YesNo
+ +Post object +----------- + +If present, Post objects must occur after the last User object in the file, but before any DirectChannel objects. + +Example Post object +~~~~~~~~~~~~~~~~~~~ + +For clarity, the object is shown using regular JSON formatting, but in the data file it cannot be spread across several lines. It must be all on one line. + +.. code-block:: javascript + + { + "type": "post", + "post": { + "team": "team-name", + "channel": "channel-name", + "user": "username", + "message": "The post message", + "props": { + "attachments": [{ + "pretext": "This is the attachment pretext.", + "text": "This is the attachment text." + }] + }, + "create_at": 140012340013, + "flagged_by": [ + "username1", + "username2", + "username3" + ], + "replies": [{ + "user": "username4", + "message": "The reply message", + "create_at": 140012352049, + "attachments": [{ + "path": "/some/valid/file/path/1" + }], + }, { + "user": "username5", + "message": "Other reply message", + "create_at": 140012353057, + }], + "reactions": [{ + "user": "username6", + "emoji_name": "+1", + "create_at": 140012356032, + }, { + "user": "username7", + "emoji_name": "heart", + "create_at": 140012359034, + }], + "attachments": [{ + "path": "/some/valid/file/path/1" + }, { + "path": "/some/valid/file/path/2" + }] + } + } + + +Fields of the Post object +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[1] Not validated, but an error occurs if the team does not exist when running in apply mode.
+ [2] Not validated, but an error occurs if the channel does not exist in the corresponding team when running in apply mode.
+ [3] Not validated, but an error occurs if the user does not exist when running in apply mode. +
Field nameTypeDescriptionValidatedMandatory
teamstringThe name of the team that this post is in.No [1]Yes
channelstringThe name of the channel that this post is in.No [2]Yes
userstringThe username of the user for this post.No [3]Yes
messagestringThe message that the post contains.YesYes
propsobjectThe props for a post. Contains additional formatting information used by integrations and bot posts. For a more detailed explanation see the message attachments documentation.YesYes
create_atintThe timestamp for the post, in milliseconds since the Unix epoch.YesYes
flagged_byarrayMust contain a list of members who have flagged the post.NoNo
repliesarrayThe posts in reply to this post. Must be an array of Reply objects.YesNo
reactionsarrayThe emoji reactions to this post. Must be an array of Reaction objects.YesNo
attachmentsarrayFile attachments associated with this post. Must be an array of Attachment objects.YesNo
+ +Fields of the Reply object +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This object is a member of the Post/DirectPost object. + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field nameTypeDescriptionValidatedMandatory
userstringThe username of the user for this reply.No [3]Yes
messagestringThe message that the reply contains.YesYes
create_atintThe timestamp for the reply, in milliseconds since the Unix epoch.YesYes
flagged_byarrayMust contain a list of members who have flagged the post.NoNo
reactionsarrayThe emoji reactions to this post. Must be an array of Reaction objects.YesNo
attachmentsarrayThe file attachments to this post. Must be an array of Attachment objects.YesNo
+ +Fields of the Reaction object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This object is a member of the Post/DirectPost object. + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field nameTypeDescriptionValidatedMandatory
userstringThe username of the user for this reply.No [3]Yes
emoji_namestringThe emoji of the reaction.YesYes
create_atintThe timestamp for the reply, in milliseconds since the Unix epoch.YesYes
+ +Fields of the Attachment object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This object is a member of the Post/DirectPost object. + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + +
+ [1] Not validated, but an error occurs if the file path is not found or accessible when running in apply mode. +
Field nameTypeDescriptionValidatedMandatory
pathstringThe path to the file to be attached to the post.No [1]Yes
+ +DirectChannel object +-------------------- + +A direct channel can have from two to eight users as members of the channel. If there are only two members, Mattermost treats it as a Direct Message channel. If there are three or more members, Mattermost treats it as a Group Message channel. + +Example DirectChannel object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For clarity, the object is shown using regular JSON formatting, but in the data file it cannot be spread across several lines. It must be all on one line. + +.. code-block:: javascript + + { + "type": "direct_channel", + "direct_channel": { + "members": [ + "username1", + "username2", + "username3" + ], + "header": "The Channel Header", + "favorited_by": [ + "username1", + "username2", + "username3" + ] + } + } + +Fields of the DirectChannel object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[1] Not validated, but an error occurs if one or more of the users don't exist when running in apply mode. +
Field nameTypeDescriptionValidatedMandatory
membersarrayMust contain a list of members, with a minimum of two usernames and a maximum of eight usernames.No [1]Yes
headerstringThe channel header.YesNo
favorited_byarrayMust contain a list of members who have favorited the channel.NoNo
+ +DirectPost object +----------------- + +DirectPost objects must occur after all other objects in the file. + +Example DirectPost object +~~~~~~~~~~~~~~~~~~~~~~~~~ + +For clarity, the object is shown using regular JSON formatting, but in the data file it cannot be spread across several lines. It must be all on one line. + +.. code-block:: javascript + + { + "type": "direct_post", + "direct_post": { + "channel_members": [ + "username1", + "username2", + "username3", + ], + "user": "username2", + "message": "Hello Group Channel", + "create_at": 140012340013, + "flagged_by": [ + "username1", + "username2", + "username3" + ], + "replies": [{ + "user": "username4", + "message": "The reply message", + "create_at": 140012352049, + }, { + "user": "username5", + "message": "Other reply message", + "create_at": 140012353057, + }], + "reactions": [{ + "user": "username6", + "emoji_name": "+1", + "create_at": 140012356032, + }, { + "user": "username7", + "emoji_name": "heart", + "create_at": 140012359034, + }] + } + } + +Fields of the DirectPost object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. raw:: html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[1] Not validated, but an error occurs if no channels contain an identical list when running in apply mode.
[2] Not validated, but an error occurs if the user does not exist when running in apply mode. +
Field nameTypeDescriptionValidatedMandatory
channel_membersarrayMust contain a list of members, with a minimum of two usernames and a maximum of eight usernames.No [1]Yes
userstringThe username of the user for this post.No [2]Yes
messagestringThe message that the post contains.YesYes
create_atintThe timestamp for the post, in milliseconds since the Unix epoch.YesYes
flagged_byarrayMust contain a list of members who have flagged the post.NoNo
repliesarrayThe posts in reply to this direct post. Must be an array of Reply objects.YesNo
reactionsarrayThe emoji reactions to this direct post. Must be an array of Reaction objects.YesNo
attachmentsarrayThe attachments to this direct post. Must be an array of Attachment objects.YesNo
+ +Common issues +------------- + +Run the bulk import command as the *mattermost* user. Running it as *root* or any other user will cause issues with file permissions on imported attachments. + +Ensure that :ref:`file attachments are enabled `, that you have enough free space in your :ref:`file storage system ` to support the incoming attachments, and that your :ref:`maximum file size ` is appropriate. + +Make sure you have enough free space for logs on the Mattermost server as well as free space on the database server for both the database itself and transaction logs. + +Disable anti-virus or any other plugins that might interfere with attachment uploading. They could potentially block uploading of attachments and cause the import to fail if configured incorrectly. If you need anti-virus scanning, scan the attachment folder before the import. + +Troubleshooting +--------------- + +Running bulk loading tool hangs and doesn't complete +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you have Bleve search indexing enabled, temporarily disable it in **System Console > Experimental > Bleve** and run the command again. + +Bleve does not support multiple processes opening and manipulating the same index. Therefore, if the Mattermost server is running, an attempt to run the bulk loading tool will lock when trying to open the indeces. + +If you are not using the Bleve search indexing, feel free to post in our :doc:`Troubleshooting forum ` for help. diff --git a/source/onboard/bulk-loading-troubleshooting.rst b/source/onboard/bulk-loading-troubleshooting.rst deleted file mode 100644 index 5c4559f9486..00000000000 --- a/source/onboard/bulk-loading-troubleshooting.rst +++ /dev/null @@ -1,14 +0,0 @@ -:orphan: -:nosearch: - -Troubleshooting ---------------- - -Running bulk loading tool hangs and doesn't complete ------------------------------------------------------ - -If you have Bleve search indexing enabled, temporarily disable it in **System Console > Experimental > Bleve** and run the command again. - -Bleve does not support multiple processes opening and manipulating the same index. Therefore, if the Mattermost server is running, an attempt to run the bulk loading tool will lock when trying to open the indeces. - -If you are not using the Bleve search indexing, feel free to post in our :doc:`Troubleshooting forum ` for help. diff --git a/source/onboard/common-disable-mfa.rst b/source/onboard/common-disable-mfa.rst deleted file mode 100644 index 0deb161956c..00000000000 --- a/source/onboard/common-disable-mfa.rst +++ /dev/null @@ -1,8 +0,0 @@ -:nosearch: - -Disabling MFA -^^^^^^^^^^^^^ - -System admins can disable this option by going to **System Console > Authentication > MFA**. When **Enable Multi-factor Authentication** is set to **false**, users can't opt to use or disable multi-factor authentication on their account via **Profile > Security > Multi-factor Authentication**. - -MFA can be disabled for user accounts using the API. See the `Mattermost API Reference `__ for details. diff --git a/source/onboard/common-sso-entraid.rst b/source/onboard/common-sso-entraid.rst deleted file mode 100644 index 13906592169..00000000000 --- a/source/onboard/common-sso-entraid.rst +++ /dev/null @@ -1,76 +0,0 @@ -:orphan: -:nosearch: - -Configuring EntraID as a Single Sign-On (SSO) service --------------------------------------------------------- - -Follow these steps to configure Mattermost to use your Entra ID logon credentials and Azure Active Directory account as a Single Sign-on (SSO) service for team creation, account creation, and sign-in. - -.. note:: - - The system must be using SSL as Microsoft only allows OAuth redirect URIs that are SSL-enabled. - -Step 1: Register an application in Azure Portal -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. Log in to the `Azure Portal `__ with the account that relates to the Azure Active Directory tenant where you want to register the application. You can confirm the tenant in the top right corner of the portal. - -2. In the left-hand navigation pane, select the **Azure Active Directory service**, then select **App registrations > New registration**. - -3. Give your new registration a **Name**. - -4. Define which **Supported account types** can access the application. For example, if this is to be only accessed from your enterprise's Azure AD accounts, then select **Accounts in this organizational directory only**. - -5. Define the **Redirect URI** as Web client, then input the URL with the host name that will be specific to your Mattermost service followed by ``/signup/office365/complete``. An example below is: ``https://your.mattermost.com/signup/office365/complete`` - -.. image:: /images/AzureApp_New_Registration.png - -.. image:: /images/AzureApp_SetupMenuv2.png - -Once the App Registration has been created, you can configure it further. See the standard `Azure AD documentation `__ for reference. - -Step 2: Generate a new client secret in Azure Portal -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. In the Azure Portal, select **Certificates and Secrets** from the menu, then select the button to generate a **New Client secret**. - -2. Provide a description, define the expiry for the token, then select **Add**. - -3. In Azure Portal, select **Overview** from the menu, then copy and paste both the Application (client) ID and the Directory (tenant) ID to a temporary location. You will enter these values as an **Application ID** and as part of an **Auth Endpoint** and **Token Endpoint** URL in the Mattermost System Console. - -.. image:: /images/AzureApp_Client_Secret_Expiry.png - -.. image:: /images/AzureApp_App_Directory_IDsv2.png - -Step 3: Configure Mattermost for Entra ID SSO -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. Log in to Mattermost, then go to **System Console > Authentication > OpenID Connect**. - -2. Select **Entra ID** as the service provider. - -3. Paste the **Directory (tenant) ID** from the Azure Portal as the **Directory (tenant) ID** in Mattermost. - -4. The **Discovery Endpoint** for OpenID Connect with Entra ID is prepopulated with ``https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration``. - -5. Paste the **Application (client) ID** from the Azure Portal as the **Client ID** in Mattermost. - -6. Paste the **client secret** value from the Azure Portal as the **Client Secret** in Mattermost. - -7. Select **Save**. - -.. note:: - When Mattermost is configured to use OpenID Connect or OAuth 2.0 for user authentication, the following user attribute changes can't be made through the Mattermost API: first name, last name, or username. OpenID Connect or OAuth 2.0 must be the authoritative source for these user attributes. - -Note about Microsoft Active Directory Tenants -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A Microsoft Active Directory (AD) tenant is a dedicated instance of Azure Active Directory (Azure AD) that you own and would have received when signing up for a Microsoft cloud service, such as Azure or Entra ID. Tenants are commonly used by organizations who want to store information about their users, such as passwords, user profile data, and permissions. You can learn more about `getting an Azure AD tenant here `__. - -To allow your Azure AD users to log in to Mattermost using Entra ID SSO, you must register Mattermost in the Microsoft Azure AD tenant that contains the users' information. The registration can be done from the `Microsoft Azure portal `__. The steps to register the Mattermost account in the tenant should be similar to those provided above, and you can find more information about `integrating apps with Azure AD here `__. - -If you don't register Mattermost in the Microsoft Azure AD tenant your organization uses, Entra ID SSO will likely fail for your users. - -.. note:: - - If you do not use Azure Active Directory, you may register Mattermost with your Entra ID or Azure account (a personal, work, or school account), then set up Entra ID SSO with Mattermost using the steps provided above. diff --git a/source/onboard/common-sso-google.rst b/source/onboard/common-sso-google.rst deleted file mode 100644 index 1b9bde0c26a..00000000000 --- a/source/onboard/common-sso-google.rst +++ /dev/null @@ -1,63 +0,0 @@ -:orphan: -:nosearch: - -Configuring Google Apps as a Single Sign-On (SSO) service ---------------------------------------------------------- - -Follow these steps to configure Mattermost to use Google as a Single Sign-on (SSO) service for team creation, account creation, and login. - -.. note:: - - The `Google People API `__ has replaced the Google+ API, which was deprecated by Google as of March 7th, 2019 `per their notice `__. - -Step 1: Create OpenID Connect project in Google API Manager -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. Go to `Google Cloud Platform `__. - -2. Select **Credentials** in the left-hand sidebar. - -3. Select **Create Credentials**, then select **OAuth client ID**. - -4. Select the **Web application** as the application type. - -5. Enter ``Mattermost-`` as the **Name**, replacing ```` with the name of your organization. - -6. Under **Authorized redirect URIs**, select **Add URL**, then enter ``{your-mattermost-url}/signup/google/complete``. For example: ``http://localhost:8065/signup/google/complete``. - -7. Select **Create**. - -8. Copy and paste the **Your Client ID** and **Your Client Secret** values to a temporary location. You will enter these values in the Mattermost System Console. - -.. image:: /images/create-google-sso-credentials.png - -.. image:: /images/select-google-sso-web-app.png - -.. image:: /images/google-sso-web-app-name.png - -.. image:: /images/google-sso-redirect-uri.png - -.. image:: /images/google-sso-credentials.png - -Step 2: Enable Google People API -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Go to the `Google People API `__, then select **Enable** in the header. This might take a few minutes to propagate through Google's systems. - -Step 3: Configure Mattermost for Google Apps SSO -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. Log in to Mattermost, then go to **System Console > Authentication > OpenID Connect**. - -2. Select **Google Apps** as the service provider. - -3. The **Discovery Endpoint** for OpenID Connect with Google Apps is prepopulated with ``https://accounts.google.com/.well-known/openid-configuration``. - -4. Paste in the **Client ID** from Google in Mattermost. - -5. Paste in the **Client Secret** from Google in Mattermost. - -6. Select **Save**. - -.. note:: - When Mattermost is configured to use OpenID Connect or OAuth 2.0 for user authentication, the following user attribute changes can't be made through the Mattermost API: first name, last name, or username. OpenID Connect or OAuth 2.0 must be the authoritative source for these user attributes. diff --git a/source/onboard/common-sso-openidconnect.rst b/source/onboard/common-sso-openidconnect.rst deleted file mode 100644 index 2886579c674..00000000000 --- a/source/onboard/common-sso-openidconnect.rst +++ /dev/null @@ -1,36 +0,0 @@ -:nosearch: - -Mattermost provides OpenID Connect support for :doc:`GitLab `, :doc:`Google Apps `, and :doc:`Entra ID `. With OpenID Connect, users can also use their login to Keycloak, Atlassian Crowd, Apple, Microsoft, Salesforce, Auth0, Ory.sh, Facebook, Okta, OneLogin, and Azure AD, as well as others, as a Single Sign-on (SSO) service for team creation, account creation, and user login. - -Follow these steps to configure a service provider using OpenID Connect. - -Step 1: Create an OpenID Connect Application ---------------------------------------------- - -1. Follow service provider documentation for creating an OpenID Connect application. Most OpenID Connect service providers require authorization of all redirect URIs. -2. In the appropriate field, enter ``{your-mattermost-url}/signup/openid/complete`` For example: ``http://domain.com/signup/openid/complete`` -3. Copy and paste values for the **Discovery Endpoint**, **Client ID**, and **Client Secret** values to a temporary location. You will enter these values when you configure Mattermost. - -Step 2: Configure Mattermost for an OpenID Connect SSO -------------------------------------------------------- - -1. Log in to Mattermost, then go to **System Console > Authentication > OpenID Connect**. -2. Select **OpenID Connect (Other)** as the service provider. -3. Enter the **Discovery Endpoint**. -4. Enter the **Client ID**. -5. Enter the **Client Secret**. -6. Specify a **Button Name** and **Button Color** for the OpenID Connect option on the Mattermost login page. -7. Select **Save**. -8. Restart your Mattermost server to see the changes take effect. - -.. note:: - - When Mattermost is configured to use OpenID Connect for user authentication, the following user attribute changes can't be made through the Mattermost API: first name, last name, or username. OpenID Connect must be the authoritative source for these user attributes. - - The **Discovery Endpoint** setting can be used to determine the connectivity and availability of arbitrary hosts. System admins concerned about this can use custom admin roles to limit access to modifying these settings. See the :ref:`delegated granular administration ` documentation for details. - -Frequently Asked Questions --------------------------- - -How can I use LDAP attributes or Groups with OpenID? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -At this time, LDAP data isn't compatible with OpenID. If you currently rely on LDAP to manage your users' teams, channels, groups, or attributes, you won't be able to do this automatically with users who have logged in with OpenID. If you need LDAP synced to each user, we suggest using SAML or LDAP as the login provider. Some OpenID providers can use SAML instead, like Keycloak. diff --git a/source/onboard/guest-account-access.rst b/source/onboard/guest-account-access.rst deleted file mode 100644 index 93be9a66a22..00000000000 --- a/source/onboard/guest-account-access.rst +++ /dev/null @@ -1,18 +0,0 @@ -:orphan: -:nosearch: - -Guests can: - -- Pin messages to channels -- Use slash commands (excluding restricted commands such as invite members, rename channels, change headers, etc) -- Favorite channels -- Mute channels -- Update their profile -- Use different authentication methods than other users - -Guests cannot: - -- Discover public channels -- Join open teams -- Create direct messages or group messages with members who aren’t within the same channel -- Invite people \ No newline at end of file diff --git a/source/onboard/guest-accounts.rst b/source/onboard/guest-accounts.rst index 011390d0595..0a3573ff6f9 100644 --- a/source/onboard/guest-accounts.rst +++ b/source/onboard/guest-accounts.rst @@ -12,8 +12,21 @@ Guest accounts Guest accounts are a way to collaborate with individuals, such as vendors and contractors, outside of your organization by controlling their access to channels and team members. For example, guest accounts can be used to collaborate with customers on a support issue or work on a website project with resources from an external design firm. -.. include:: /onboard/guest-account-access.rst - :start-after: :nosearch: +Guests can: + +- Pin messages to channels +- Use slash commands (excluding restricted commands such as invite members, rename channels, change headers, etc) +- Favorite channels +- Mute channels +- Update their profile +- Use different authentication methods than other users + +Guests cannot: + +- Discover public channels +- Join open teams +- Create direct messages or group messages with members who aren’t within the same channel +- Invite people .. important:: diff --git a/source/onboard/multi-factor-authentication.rst b/source/onboard/multi-factor-authentication.rst index 80510a6d1be..83a140f616a 100644 --- a/source/onboard/multi-factor-authentication.rst +++ b/source/onboard/multi-factor-authentication.rst @@ -25,8 +25,12 @@ System admins can enable this option by going to **System Console > Authenticati Once enabled, users can choose to :doc:`set up multi-factor authentication ` on their account by selecting **Profile > Security > Multi-factor Authentication** from their profile picture. -.. include:: common-disable-mfa.rst - :start-after: :nosearch: +Disabling MFA +~~~~~~~~~~~~~ + +System admins can disable this option by going to **System Console > Authentication > MFA**. When **Enable Multi-factor Authentication** is set to **false**, users can't opt to use or disable multi-factor authentication on their account via **Profile > Security > Multi-factor Authentication**. + +MFA can be disabled for user accounts using the API. See the `Mattermost API Reference `__ for details. Enforcing MFA -------------- diff --git a/source/onboard/run-bulk-loading-command.rst b/source/onboard/run-bulk-loading-command.rst deleted file mode 100644 index 0538e1e8d61..00000000000 --- a/source/onboard/run-bulk-loading-command.rst +++ /dev/null @@ -1,24 +0,0 @@ -:nosearch: - -Bulk load data ---------------- - -Before running the bulk loading command, you must first create a `JSONL `__ file that contains the data that you want to import in your Mattermost directory. The file can have any name, but in this example it's called ``data.jsonl``. The format of the file is described in the :ref:`data-format ` section. - -Next, zip it by running the ``zip -r data.zip data.jsonl`` command. - -Using mmctl local mode -~~~~~~~~~~~~~~~~~~~~~~ - -From Mattermost v9.5, the mmctl bulk import process command in :ref:`local mode ` supports processing an import file without uploading it to the server. - -Run ``mmctl import process --bypass-upload .zip --local`` to start your import and enable the Mattermost server to read from the file directly. - -Not using mmctl local mode -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you're not running mmctl commands in local mode: - -1. Upload the ZIP file to the database by running the :ref:`mmctl import upload ` command. For example: ``mmctl import upload data.zip``. -2. Confirm that the file is uploaded and ready for use by running the :ref:`mmctl import list available ` command. -3. Import your uploaded file by running the :ref:`mmctl import process ` command. For example: ``mmctl import process _data.zip`` (use the name of the uploaded file from :ref:`mmctl import list available ` command). \ No newline at end of file diff --git a/source/onboard/sso-entraid.rst b/source/onboard/sso-entraid.rst index 683cdad3317..30123f7b701 100644 --- a/source/onboard/sso-entraid.rst +++ b/source/onboard/sso-entraid.rst @@ -8,8 +8,79 @@ Entra ID Single Sign-On

Also available in legacy Mattermost Enterprise Edition E20

-.. include:: common-sso-entraid.rst - :start-after: :nosearch: +Configuring EntraID as a Single Sign-On (SSO) service +-------------------------------------------------------- + +Follow these steps to configure Mattermost to use your Entra ID logon credentials and Azure Active Directory account as a Single Sign-on (SSO) service for team creation, account creation, and sign-in. + +.. note:: + + The system must be using SSL as Microsoft only allows OAuth redirect URIs that are SSL-enabled. + +Step 1: Register an application in Azure Portal +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Log in to the `Azure Portal `__ with the account that relates to the Azure Active Directory tenant where you want to register the application. You can confirm the tenant in the top right corner of the portal. + +2. In the left-hand navigation pane, select the **Azure Active Directory service**, then select **App registrations > New registration**. + +3. Give your new registration a **Name**. + +4. Define which **Supported account types** can access the application. For example, if this is to be only accessed from your enterprise's Azure AD accounts, then select **Accounts in this organizational directory only**. + +5. Define the **Redirect URI** as Web client, then input the URL with the host name that will be specific to your Mattermost service followed by ``/signup/office365/complete``. An example below is: ``https://your.mattermost.com/signup/office365/complete`` + +.. image:: /images/AzureApp_New_Registration.png + +.. image:: /images/AzureApp_SetupMenuv2.png + +Once the App Registration has been created, you can configure it further. See the standard `Azure AD documentation `__ for reference. + +Step 2: Generate a new client secret in Azure Portal +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. In the Azure Portal, select **Certificates and Secrets** from the menu, then select the button to generate a **New Client secret**. + +2. Provide a description, define the expiry for the token, then select **Add**. + +3. In Azure Portal, select **Overview** from the menu, then copy and paste both the Application (client) ID and the Directory (tenant) ID to a temporary location. You will enter these values as an **Application ID** and as part of an **Auth Endpoint** and **Token Endpoint** URL in the Mattermost System Console. + +.. image:: /images/AzureApp_Client_Secret_Expiry.png + +.. image:: /images/AzureApp_App_Directory_IDsv2.png + +Step 3: Configure Mattermost for Entra ID SSO +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Log in to Mattermost, then go to **System Console > Authentication > OpenID Connect**. + +2. Select **Entra ID** as the service provider. + +3. Paste the **Directory (tenant) ID** from the Azure Portal as the **Directory (tenant) ID** in Mattermost. + +4. The **Discovery Endpoint** for OpenID Connect with Entra ID is prepopulated with ``https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration``. + +5. Paste the **Application (client) ID** from the Azure Portal as the **Client ID** in Mattermost. + +6. Paste the **client secret** value from the Azure Portal as the **Client Secret** in Mattermost. + +7. Select **Save**. + +.. note:: + When Mattermost is configured to use OpenID Connect or OAuth 2.0 for user authentication, the following user attribute changes can't be made through the Mattermost API: first name, last name, or username. OpenID Connect or OAuth 2.0 must be the authoritative source for these user attributes. + +Note about Microsoft Active Directory Tenants +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A Microsoft Active Directory (AD) tenant is a dedicated instance of Azure Active Directory (Azure AD) that you own and would have received when signing up for a Microsoft cloud service, such as Azure or Entra ID. Tenants are commonly used by organizations who want to store information about their users, such as passwords, user profile data, and permissions. You can learn more about `getting an Azure AD tenant here `__. + +To allow your Azure AD users to log in to Mattermost using Entra ID SSO, you must register Mattermost in the Microsoft Azure AD tenant that contains the users' information. The registration can be done from the `Microsoft Azure portal `__. The steps to register the Mattermost account in the tenant should be similar to those provided above, and you can find more information about `integrating apps with Azure AD here `__. + +If you don't register Mattermost in the Microsoft Azure AD tenant your organization uses, Entra ID SSO will likely fail for your users. + +.. note:: + + If you do not use Azure Active Directory, you may register Mattermost with your Entra ID or Azure account (a personal, work, or school account), then set up Entra ID SSO with Mattermost using the steps provided above. Configure Mattermost ``config.json`` for Entra ID SSO ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/onboard/sso-google.rst b/source/onboard/sso-google.rst index bf309175ef3..4c0c0d619fa 100644 --- a/source/onboard/sso-google.rst +++ b/source/onboard/sso-google.rst @@ -8,8 +8,66 @@ Google Single Sign-On

Also available in legacy Mattermost Enterprise Edition E20

-.. include:: common-sso-google.rst - :start-after: :nosearch: +Configuring Google Apps as a Single Sign-On (SSO) service +--------------------------------------------------------- + +Follow these steps to configure Mattermost to use Google as a Single Sign-on (SSO) service for team creation, account creation, and login. + +.. note:: + + The `Google People API `__ has replaced the Google+ API, which was deprecated by Google as of March 7th, 2019 `per their notice `__. + +Step 1: Create OpenID Connect project in Google API Manager +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Go to `Google Cloud Platform `__. + +2. Select **Credentials** in the left-hand sidebar. + +3. Select **Create Credentials**, then select **OAuth client ID**. + +4. Select the **Web application** as the application type. + +5. Enter ``Mattermost-`` as the **Name**, replacing ```` with the name of your organization. + +6. Under **Authorized redirect URIs**, select **Add URL**, then enter ``{your-mattermost-url}/signup/google/complete``. For example: ``http://localhost:8065/signup/google/complete``. + +7. Select **Create**. + +8. Copy and paste the **Your Client ID** and **Your Client Secret** values to a temporary location. You will enter these values in the Mattermost System Console. + +.. image:: /images/create-google-sso-credentials.png + +.. image:: /images/select-google-sso-web-app.png + +.. image:: /images/google-sso-web-app-name.png + +.. image:: /images/google-sso-redirect-uri.png + +.. image:: /images/google-sso-credentials.png + +Step 2: Enable Google People API +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Go to the `Google People API `__, then select **Enable** in the header. This might take a few minutes to propagate through Google's systems. + +Step 3: Configure Mattermost for Google Apps SSO +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Log in to Mattermost, then go to **System Console > Authentication > OpenID Connect**. + +2. Select **Google Apps** as the service provider. + +3. The **Discovery Endpoint** for OpenID Connect with Google Apps is prepopulated with ``https://accounts.google.com/.well-known/openid-configuration``. + +4. Paste in the **Client ID** from Google in Mattermost. + +5. Paste in the **Client Secret** from Google in Mattermost. + +6. Select **Save**. + +.. note:: + When Mattermost is configured to use OpenID Connect or OAuth 2.0 for user authentication, the following user attribute changes can't be made through the Mattermost API: first name, last name, or username. OpenID Connect or OAuth 2.0 must be the authoritative source for these user attributes. Configure Mattermost ``config.json`` for Google Apps SSO ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/onboard/sso-openidconnect.rst b/source/onboard/sso-openidconnect.rst index b9cb79e8c6d..1128399ba61 100644 --- a/source/onboard/sso-openidconnect.rst +++ b/source/onboard/sso-openidconnect.rst @@ -8,5 +8,37 @@ OpenID Connect Single Sign-On

Also available in legacy Mattermost Enterprise Edition E20

-.. include:: common-sso-openidconnect.rst - :start-after: :nosearch: \ No newline at end of file +Mattermost provides OpenID Connect support for :doc:`GitLab `, :doc:`Google Apps `, and :doc:`Entra ID `. With OpenID Connect, users can also use their login to Keycloak, Atlassian Crowd, Apple, Microsoft, Salesforce, Auth0, Ory.sh, Facebook, Okta, OneLogin, and Azure AD, as well as others, as a Single Sign-on (SSO) service for team creation, account creation, and user login. + +Follow these steps to configure a service provider using OpenID Connect. + +Step 1: Create an OpenID Connect Application +--------------------------------------------- + +1. Follow service provider documentation for creating an OpenID Connect application. Most OpenID Connect service providers require authorization of all redirect URIs. +2. In the appropriate field, enter ``{your-mattermost-url}/signup/openid/complete`` For example: ``http://domain.com/signup/openid/complete`` +3. Copy and paste values for the **Discovery Endpoint**, **Client ID**, and **Client Secret** values to a temporary location. You will enter these values when you configure Mattermost. + +Step 2: Configure Mattermost for an OpenID Connect SSO +------------------------------------------------------- + +1. Log in to Mattermost, then go to **System Console > Authentication > OpenID Connect**. +2. Select **OpenID Connect (Other)** as the service provider. +3. Enter the **Discovery Endpoint**. +4. Enter the **Client ID**. +5. Enter the **Client Secret**. +6. Specify a **Button Name** and **Button Color** for the OpenID Connect option on the Mattermost login page. +7. Select **Save**. +8. Restart your Mattermost server to see the changes take effect. + +.. note:: + - When Mattermost is configured to use OpenID Connect for user authentication, the following user attribute changes can't be made through the Mattermost API: first name, last name, or username. OpenID Connect must be the authoritative source for these user attributes. + - The **Discovery Endpoint** setting can be used to determine the connectivity and availability of arbitrary hosts. System admins concerned about this can use custom admin roles to limit access to modifying these settings. See the :ref:`delegated granular administration ` documentation for details. + +Frequently Asked Questions +-------------------------- + +How can I use LDAP attributes or Groups with OpenID? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +At this time, LDAP data isn't compatible with OpenID. If you currently rely on LDAP to manage your users' teams, channels, groups, or attributes, you won't be able to do this automatically with users who have logged in with OpenID. If you need LDAP synced to each user, we suggest using SAML or LDAP as the login provider. Some OpenID providers can use SAML instead, like Keycloak. \ No newline at end of file diff --git a/source/onboard/sso-saml-before-you-begin.rst b/source/onboard/sso-saml-before-you-begin.rst index f7f992be3c3..a294f6f4fff 100644 --- a/source/onboard/sso-saml-before-you-begin.rst +++ b/source/onboard/sso-saml-before-you-begin.rst @@ -1,5 +1,8 @@ +:orphan: :nosearch: +.. This page is intentionally not accessible via the LHS navigation pane because it's common content included on other docs pages. + Before you begin ---------------- diff --git a/source/onboard/sso-saml-faq.rst b/source/onboard/sso-saml-faq.rst index 4a77bf6ef84..19e929b249d 100644 --- a/source/onboard/sso-saml-faq.rst +++ b/source/onboard/sso-saml-faq.rst @@ -1,5 +1,8 @@ +:orphan: :nosearch: +.. This page is intentionally not accessible via the LHS navigation pane because it's common content included on other docs pages. + Frequently Asked Questions -------------------------- diff --git a/source/scale/high-availability-cluster-based-deployment.rst b/source/scale/high-availability-cluster-based-deployment.rst index c5489dd7f61..26917b3b740 100644 --- a/source/scale/high-availability-cluster-based-deployment.rst +++ b/source/scale/high-availability-cluster-based-deployment.rst @@ -37,7 +37,7 @@ To ensure your instance and configuration are compatible with a high availabilit Back up your Mattermost database and file storage locations before configuring high availability. For more information about backing up, see :doc:`../deploy/backup-disaster-recovery`. 1. Set up a new Mattermost server by following one of our **Install Guides**. This server must use an identical copy of the configuration file, ``config.json``. Verify the servers are functioning by hitting each independent server through its private IP address. -2. Modify the ``config.json`` files on both servers to add ``ClusterSettings``. See the :doc:`high availability cluster-based deployment configuration settings ` documentation for details. +2. Modify the ``config.json`` files on both servers to add ``ClusterSettings``. See the :ref:`high availability cluster-based deployment configuration settings ` documentation for details. 3. Verify the configuration files are identical on both servers then restart each machine in the cluster. 4. Modify your NGINX setup so that it proxies to both servers. For more information about this, see `proxy server configuration`_. 5. Open **System Console > Environment > High Availability** to verify that each machine in the cluster is communicating as expected with green status indicators. If not, investigate the log files for any extra information. From 58a2070ecbf4286cb9768e884941e6f988bfd86a Mon Sep 17 00:00:00 2001 From: Ibrahim Serdar Acikgoz Date: Mon, 28 Oct 2024 06:04:25 +0100 Subject: [PATCH 2/3] mysql deprecation: add more troubleshooting steps (#7510) --- source/deploy/postgres-migration.rst | 50 ++++++++++++++++++++++++++-- 1 file changed, 48 insertions(+), 2 deletions(-) diff --git a/source/deploy/postgres-migration.rst b/source/deploy/postgres-migration.rst index 53f86014a15..d5303ff1f06 100644 --- a/source/deploy/postgres-migration.rst +++ b/source/deploy/postgres-migration.rst @@ -61,9 +61,55 @@ Errors during the pgloader command execution If you encounter errors during the execution of the ``pgloader`` command, ensure that both of the databases are accessible and that the users have the necessary permissions to access the database. Do not continue with the migration if there are errors during the execution of the ``pgloader`` command. -Also, there may be cases where ``pgloader`` continue to migration remaining tables and skip one or more tables. In such cases, it is recommended to identify issues with the table and fix them before running the ``pgloader`` command again with a clean database. It is possible to run the ``pgloader`` command with the ``--debug`` flag to get more information about the errors. +.. note:: + + For experienced users, it is recoverable to run the ``pgloader`` without requiring a restart of the migration from scratch. In this case, you will need to manually fix the issues with the table, and run the ``pgloader`` command with a tailored configuration specifically for those tables. Also ensure that the schema name is reverted back to ``public``, and the ``search_path`` is restored (or remove necessary clauses from the configuration). + +The following sections detail how to resolve some common errors you may encounter during the execution of the ``pgloader`` command: + +Invalid input syntax for type JSON +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you receive an error message similar to the following: + +.. code-block:: text + + ERROR Database error 22P02: invalid input syntax for type json + +The data in the MySQL database is not in a valid JSON format. You can fix this issue by updating the data in the MySQL database to be in a valid JSON format. To find out which row is causing the issue, run the following query (where ```` and ```` should be replaced with the actual table and column names indicated in the ``pgloader`` output): + +.. code-block:: sql + + SELECT * FROM WHERE JSON_VALID() = 0; + +You can find and update the data in the MySQL database to be in a valid JSON format with the query above. After updating the data, you can run the ``pgloader`` command again. + +Failed to find column or table +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you receive an error message similar to the following: + +.. code-block:: text + + pgloader failed to find column + +The column or table is missing in the PostgreSQL database. You can fix this issue by checking whether you have created the correct version of Postgres schema. After re-creating the schema, you can run the ``pgloader`` command again. + +Fell through ECASE expression +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you receive an error message similar to the following: + +.. code-block:: text + + ERROR mysql: 76 fell through ECASE expression. + +It is a `known issue `_ with pgloader. You can fix this issue by either compiling ``pgloader`` from source or simply avoid this by running ``pgloader`` with our docker image. See: :ref:`install pgloader ` for more information. + +.. note:: + + Also, there may be cases where pgloader continues to migrate remaining tables and skip one or more tables during migration. In such cases, we recommend identifying issues with the table and fixing them before running the ``pgloader`` command again with a clean database. It is possible to run the ``pgloader`` command with the ``--debug`` flag to get more information about the errors. -For experienced users, it is recoverable to run the ``pgloader`` without requiring to restart the migration from scratch. In this case, you will need to manually fix the issues with the table and run the ``pgloader`` command with a tailored configuration just for those tables. Also ensure that the schema name is reverted back to ``public`` and the ``search_path`` is restored or remove necessary clauses form the configuration. Mattermost can't connect to the PostgreSQL database ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From fdbdfb9e063c17103db77f13440fb73e6cbcc6de Mon Sep 17 00:00:00 2001 From: Amy Blais <29708087+amyblais@users.noreply.github.com> Date: Mon, 28 Oct 2024 08:58:26 -0400 Subject: [PATCH 3/3] Dot release docs (#7499) * Update mattermost-server-releases.md * Update version-archive.rst * Update download-latest-tarball.rst * Update mattermost-v9-changelog.md * Update mattermost-v10-changelog.md * Update mattermost-v10-changelog.md * Update mattermost-v10-changelog.md * Update mattermost-v10-changelog.md * Update mattermost-v9-changelog.md * Update mattermost-v9-changelog.md * Update mattermost-v9-changelog.md * Update mattermost-v10-changelog.md * Update mattermost-v10-changelog.md * Update mattermost-v10-changelog.md * Update mattermost-v9-changelog.md * Update version-archive.rst * Update version-archive.rst * Update version-archive.rst --- source/about/mattermost-server-releases.md | 8 +-- source/about/mattermost-v10-changelog.md | 10 ++++ source/about/mattermost-v9-changelog.md | 8 +++ source/about/version-archive.rst | 64 +++++++++++----------- source/install/download-latest-tarball.rst | 4 +- 5 files changed, 56 insertions(+), 38 deletions(-) diff --git a/source/about/mattermost-server-releases.md b/source/about/mattermost-server-releases.md index 0fa6b00d4c3..53222b1b986 100644 --- a/source/about/mattermost-server-releases.md +++ b/source/about/mattermost-server-releases.md @@ -19,15 +19,15 @@ Mattermost releases a new server version on the 16th of each month in [binary fo | **Release** | **Released on** | **Support ends** | |:---|:---|:---| -| v10.1 [Download](https://releases.mattermost.com/10.1.1/mattermost-10.1.1-linux-amd64.tar.gz) \| {ref}`Changelog ` | 2024-10-16 | 2025-01-15 | -| v10.0 [Download](https://releases.mattermost.com/10.0.1/mattermost-10.0.1-linux-amd64.tar.gz) \| {ref}`Changelog ` | 2024-09-16 | 2024-12-15 | -| v9.11 [Download](https://releases.mattermost.com/9.11.3/mattermost-9.11.3-linux-amd64.tar.gz) \| {ref}`Changelog ` | 2024-08-16 | 2025-05-15 {ref}`EXTENDED ` | +| v10.1 [Download](https://releases.mattermost.com/10.1.2/mattermost-10.1.2-linux-amd64.tar.gz) \| {ref}`Changelog ` | 2024-10-16 | 2025-01-15 | +| v10.0 [Download](https://releases.mattermost.com/10.0.2/mattermost-10.0.2-linux-amd64.tar.gz) \| {ref}`Changelog ` | 2024-09-16 | 2024-12-15 | +| v9.11 [Download](https://releases.mattermost.com/9.11.4/mattermost-9.11.4-linux-amd64.tar.gz) \| {ref}`Changelog ` | 2024-08-16 | 2025-05-15 {ref}`EXTENDED ` | | v9.10 [Download](https://releases.mattermost.com/9.10.3/mattermost-9.10.3-linux-amd64.tar.gz) \| {ref}`Changelog ` | 2024-07-16 | 2024-10-15 | | v9.9 [Download](https://releases.mattermost.com/9.9.3/mattermost-9.9.3-linux-amd64.tar.gz) \| {ref}`Changelog ` | 2024-06-14 | 2024-09-15 | | v9.8 [Download](https://releases.mattermost.com/9.8.3/mattermost-9.8.3-linux-amd64.tar.gz) \| {ref}`Changelog ` | 2024-05-16 | 2024-08-15 | | v9.7 [Download](https://releases.mattermost.com/9.7.6/mattermost-9.7.6-linux-amd64.tar.gz) \| {ref}`Changelog ` | 2024-04-16 | 2024-07-15 | | v9.6 [Download](https://releases.mattermost.com/9.6.3/mattermost-9.6.3-linux-amd64.tar.gz) \| {ref}`Changelog ` | 2024-03-16 | 2024-06-15 | -| v9.5 [Download](https://releases.mattermost.com/9.5.11/mattermost-9.5.11-linux-amd64.tar.gz) \| {ref}`Changelog ` | 2024-02-16 | 2024-11-15 {ref}`EXTENDED ` | +| v9.5 [Download](https://releases.mattermost.com/9.5.12/mattermost-9.5.12-linux-amd64.tar.gz) \| {ref}`Changelog ` | 2024-02-16 | 2024-11-15 {ref}`EXTENDED ` | | v9.4 [Download](https://releases.mattermost.com/9.4.5/mattermost-9.4.5-linux-amd64.tar.gz) \| {ref}`Changelog ` | 2024-01-16 | 2024-04-15 | | v9.3 [Download](https://releases.mattermost.com/9.3.3/mattermost-9.3.3-linux-amd64.tar.gz) \| {ref}`Changelog ` | 2023-12-16 | 2024-03-15 | | v9.2 [Download](https://releases.mattermost.com/9.2.6/mattermost-9.2.6-linux-amd64.tar.gz) \| {ref}`Changelog ` | 2023-11-16 | 2024-02-15 | diff --git a/source/about/mattermost-v10-changelog.md b/source/about/mattermost-v10-changelog.md index 0bad784488c..02ef32ff8b1 100644 --- a/source/about/mattermost-v10-changelog.md +++ b/source/about/mattermost-v10-changelog.md @@ -10,6 +10,11 @@ Support for Mattermost Server v9.5 [Extended Support Release](https://docs.matte (release-v10.1-feature-release)= ## Release v10.1 - [Feature Release](https://docs.mattermost.com/about/release-policy.html#release-types) +- **10.1.2, released 2024-10-28** + - Mattermost v10.1.2 contains a high severity level security fix. [Upgrading](https://docs.mattermost.com/upgrade/upgrading-mattermost-server.html) to this release is recommended. Details will be posted on our [security updates page](https://mattermost.com/security-updates/) 30 days after release as per the [Mattermost Responsible Disclosure Policy](https://mattermost.com/security-vulnerability-report/). + - Fixed an issue with message export file attachments with a dedicated filestore [MM-60063](https://mattermost.atlassian.net/browse/MM-60063). + - Mattermost v10.1.2 contains the following functional change: + - Added a configuration setting **NativeAppSettings > MobileExternalBrowser** that tells the Mobile app to perform SSO Authentication using the external default browser [MM-60332](https://mattermost.atlassian.net/browse/MM-60332). - **10.1.1, released 2024-10-16** - Fixed an issue where a shared indicator was shown in all Direct Messages, regardless of the user coming from a shared server [MM-60744](https://mattermost.atlassian.net/browse/MM-60744). - Mattermost v10.1.1 contains no database or functional changes. @@ -87,6 +92,11 @@ New setting options were added to ``config.json``. Below is a list of the additi (release-v10.0-major-release)= ## Release v10.0 - [Major Release](https://docs.mattermost.com/about/release-policy.html#release-types) +- **10.0.2, released 2024-10-28** + - Mattermost v10.0.2 contains a high severity level security fix. [Upgrading](https://docs.mattermost.com/upgrade/upgrading-mattermost-server.html) to this release is recommended. Details will be posted on our [security updates page](https://mattermost.com/security-updates/) 30 days after release as per the [Mattermost Responsible Disclosure Policy](https://mattermost.com/security-vulnerability-report/). + - Reverted a change enforcing usernames to start with alpha characters on the server [MM-61143](https://mattermost.atlassian.net/browse/MM-61143). + - Reverted a breaking change in ``registerSlashCommandWillBePostedHook`` that caused errors to surface in case an expected empty object was returned [MM-61233](https://mattermost.atlassian.net/browse/MM-61233). + - Mattermost v10.0.2 contains no database or functional changes. - **10.0.1, released 2024-10-10** - Mattermost v10.0.1 contains low to medium severity level security fixes. [Upgrading](https://docs.mattermost.com/upgrade/upgrading-mattermost-server.html) to this release is recommended. Details will be posted on our [security updates page](https://mattermost.com/security-updates/) 30 days after release as per the [Mattermost Responsible Disclosure Policy](https://mattermost.com/security-vulnerability-report/). - Fixed an issue enabling Professional customers and Team Edition users to upgrade to Playbooks v2 via the in-product marketplace, which fails to start without an Enterprise License. Additional details and discussion can be found on the [forums here](https://forum.mattermost.com/t/clarification-on-playbooks-in-mattermost-v10/20563) [MM-60679](https://mattermost.atlassian.net/browse/MM-60679). diff --git a/source/about/mattermost-v9-changelog.md b/source/about/mattermost-v9-changelog.md index 8479c32497b..91afe7a02e3 100644 --- a/source/about/mattermost-v9-changelog.md +++ b/source/about/mattermost-v9-changelog.md @@ -10,6 +10,10 @@ Support for Mattermost Server v9.5 [Extended Support Release](https://docs.matte (release-v9-11-extended-support-release)= ## Release v9.11 - [Extended Support Release](https://docs.mattermost.com/about/release-policy.html#release-types) +- **9.11.4, released 2024-10-28** + - Mattermost v9.11.4 contains a high severity level security fix. [Upgrading](https://docs.mattermost.com/upgrade/upgrading-mattermost-server.html) to this release is recommended. Details will be posted on our [security updates page](https://mattermost.com/security-updates/) 30 days after release as per the [Mattermost Responsible Disclosure Policy](https://mattermost.com/security-vulnerability-report/). + - Fixed an issue where users would not see channels they were added to/messages from those channels in clustered environments [MM-59911](https://mattermost.atlassian.net/browse/MM-59911). + - Mattermost v9.11.4 contains no database or functional changes. - **9.11.3, released 2024-10-10** - Mattermost v9.11.3 contains low to medium severity level security fixes. [Upgrading](https://docs.mattermost.com/upgrade/upgrading-mattermost-server.html) to this release is recommended. Details will be posted on our [security updates page](https://mattermost.com/security-updates/) 30 days after release as per the [Mattermost Responsible Disclosure Policy](https://mattermost.com/security-vulnerability-report/). - Fixed an issue with YouTube previews no longer being displayed [MM-60351](https://mattermost.atlassian.net/browse/MM-60351). @@ -664,6 +668,10 @@ See [this walkthrough video](https://mattermost.com/video/changelog-v9-6/) on so (release-v9-5-extended-support-release)= ## Release v9.5 - [Extended Support Release](https://docs.mattermost.com/upgrade/release-definitions.html#extended-support-release-esr) +- **9.5.12, released 2024-10-28** + - Mattermost v9.5.12 contains a high severity level security fix. [Upgrading](https://docs.mattermost.com/upgrade/upgrading-mattermost-server.html) to this release is recommended. Details will be posted on our [security updates page](https://mattermost.com/security-updates/) 30 days after release as per the [Mattermost Responsible Disclosure Policy](https://mattermost.com/security-vulnerability-report/). + - Fixed desyncing issues with unreads between the team sidebar and the title bar [MM-54021](https://mattermost.atlassian.net/browse/MM-54021). + - Mattermost v9.5.12 contains no database or functional changes. - **9.5.11, released 2024-10-10** - Mattermost v9.5.11 contains low to medium severity level security fixes. [Upgrading](https://docs.mattermost.com/upgrade/upgrading-mattermost-server.html) to this release is recommended. Details will be posted on our [security updates page](https://mattermost.com/security-updates/) 30 days after release as per the [Mattermost Responsible Disclosure Policy](https://mattermost.com/security-vulnerability-report/). - Fixed an issue with YouTube previews no longer being displayed [MM-60351](https://mattermost.atlassian.net/browse/MM-60351). diff --git a/source/about/version-archive.rst b/source/about/version-archive.rst index 81fa22a432d..f70c3990860 100644 --- a/source/about/version-archive.rst +++ b/source/about/version-archive.rst @@ -11,18 +11,18 @@ Version archive .. tab:: Mattermost Enterprise - Mattermost Enterprise Edition v10.1.1 - `View Changelog `__ - `Download `__ - - ``https://releases.mattermost.com/10.1.1/mattermost-10.1.1-linux-amd64.tar.gz`` - - SHA-256 Checksum: ``aaeb49e8891780ff20ac5a09fe3ee624145404fc4dda72a5174e85cb2744ffa6`` - - GPG Signature: https://releases.mattermost.com/10.1.1/mattermost-10.1.1-linux-amd64.tar.gz.sig - Mattermost Enterprise Edition v10.0.1 - `View Changelog `__ - `Download `__ - - ``https://releases.mattermost.com/10.0.1/mattermost-10.0.1-linux-amd64.tar.gz`` - - SHA-256 Checksum: ``c0e8242168968bf7c9dce0c5a3a372183d1056eb6d92cd095e812b0e28bca761`` - - GPG Signature: https://releases.mattermost.com/10.0.1/mattermost-10.0.1-linux-amd64.tar.gz.sig - Mattermost Enterprise Edition v9.11.3 *Extended Support Release (ESR)* - `View Changelog `__ - `Download `__ - - ``https://releases.mattermost.com/9.11.3/mattermost-9.11.3-linux-amd64.tar.gz`` - - SHA-256 Checksum: ``e09ce12f6f86dd3f7ca4d1602ae82cfdea12adb9bb41293982b565a6bac82842`` - - GPG Signature: https://releases.mattermost.com/9.11.3/mattermost-9.11.3-linux-amd64.tar.gz.sig + Mattermost Enterprise Edition v10.1.2 - `View Changelog `__ - `Download `__ + - ``https://releases.mattermost.com/10.1.2/mattermost-10.1.2-linux-amd64.tar.gz`` + - SHA-256 Checksum: ``b5870b3e944957268f59c823d189fa195629085d445004d0919545a87278f609`` + - GPG Signature: https://releases.mattermost.com/10.1.2/mattermost-10.1.2-linux-amd64.tar.gz.sig + Mattermost Enterprise Edition v10.0.2 - `View Changelog `__ - `Download `__ + - ``https://releases.mattermost.com/10.0.2/mattermost-10.0.2-linux-amd64.tar.gz`` + - SHA-256 Checksum: ``8447dfa0d0c9788ba7b3cb06b94dcefb33129f76a121a29f46acfe29c27472a9`` + - GPG Signature: https://releases.mattermost.com/10.0.2/mattermost-10.0.2-linux-amd64.tar.gz.sig + Mattermost Enterprise Edition v9.11.4 *Extended Support Release (ESR)* - `View Changelog `__ - `Download `__ + - ``https://releases.mattermost.com/9.11.4/mattermost-9.11.4-linux-amd64.tar.gz`` + - SHA-256 Checksum: ``9388ad2b28e29fe2112aa95be19abbea3b3bf60db7a7bcad2dcf9e6b9439730e`` + - GPG Signature: https://releases.mattermost.com/9.11.4/mattermost-9.11.4-linux-amd64.tar.gz.sig Mattermost Enterprise Edition v9.10.3 - `View Changelog `__ - `Download `__ - ``https://releases.mattermost.com/9.10.3/mattermost-9.10.3-linux-amd64.tar.gz`` - SHA-256 Checksum: ``638433634efbffe3c1d373b3f344406d37fcc3ab86292d4381890e3eeb86fb9d`` @@ -43,10 +43,10 @@ Version archive - ``https://releases.mattermost.com/9.6.3/mattermost-9.6.3-linux-amd64.tar.gz`` - SHA-256 Checksum: ``a636fbfb994dc4d4a5debd775149e17ae08d5af159c39d458facb7d8188ba4e4`` - GPG Signature: https://releases.mattermost.com/9.6.3/mattermost-9.6.3-linux-amd64.tar.gz.sig - Mattermost Enterprise Edition v9.5.11 *Extended Support Release (ESR)* - `View Changelog `__ - `Download `__ - - ``https://releases.mattermost.com/9.5.11/mattermost-9.5.11-linux-amd64.tar.gz`` - - SHA-256 Checksum: ``7510740aa5281089020e51ffbdc9ff4b54cb961cfd896a7ad56336924f93a199`` - - GPG Signature: https://releases.mattermost.com/9.5.11/mattermost-9.5.11-linux-amd64.tar.gz.sig + Mattermost Enterprise Edition v9.5.12 *Extended Support Release (ESR)* - `View Changelog `__ - `Download `__ + - ``https://releases.mattermost.com/9.5.12/mattermost-9.5.12-linux-amd64.tar.gz`` + - SHA-256 Checksum: ``71e3dd9550df94f6e29392b6a95a6617467788ea04063a59c8684664a5925e24`` + - GPG Signature: https://releases.mattermost.com/9.5.12/mattermost-9.5.12-linux-amd64.tar.gz.sig Mattermost Enterprise Edition v9.4.5 - `View Changelog `__ - `Download `__ - ``https://releases.mattermost.com/9.4.5/mattermost-9.4.5-linux-amd64.tar.gz`` - SHA-256 Checksum: ``17a49bfe180bc51a6ed33597fe713afed7f5a586e9f7adcb88e5c58c7860ba4c`` @@ -387,18 +387,18 @@ Version archive We generally recommend installing Enterprise Edition, even if you don't currently need a license. This provides the flexibility to seamlessly unlock Enterprise features should you need them. However, if you only want to install software with a fully open source code base, then Team Edition is the best choice for you. - Mattermost Team Edition v10.1.1 - `View Changelog `__ - `Download `__ - - ``https://releases.mattermost.com/10.1.1/mattermost-team-10.1.1-linux-amd64.tar.gz`` - - SHA-256 Checksum: ``5b08c9685950b22611d56d0a0e77b25d0d57f201a54cc2a8b7148608d5f048af`` - - GPG Signature: https://releases.mattermost.com/10.1.1/mattermost-team-10.1.1-linux-amd64.tar.gz.sig - Mattermost Team Edition v10.0.1 - `View Changelog `__ - `Download `__ - - ``https://releases.mattermost.com/10.0.1/mattermost-team-10.0.1-linux-amd64.tar.gz`` - - SHA-256 Checksum: ``932090fd6fbc44e33ddcdc57f89fe1048c3a1d486de3b0395839aef47a182b77`` - - GPG Signature: https://releases.mattermost.com/10.0.1/mattermost-team-10.0.1-linux-amd64.tar.gz.sig - Mattermost Team Edition v9.11.3 *Extended Support Release (ESR)* - `View Changelog `__ - `Download `__ - - ``https://releases.mattermost.com/9.11.3/mattermost-team-9.11.3-linux-amd64.tar.gz`` - - SHA-256 Checksum: ``459c00d8d6b7a103d37ab920b0bb64af0990ab2fe32395aa5cba0efb8e406abb`` - - GPG Signature: https://releases.mattermost.com/9.11.3/mattermost-team-9.11.3-linux-amd64.tar.gz.sig + Mattermost Team Edition v10.1.2 - `View Changelog `__ - `Download `__ + - ``https://releases.mattermost.com/10.1.2/mattermost-team-10.1.2-linux-amd64.tar.gz`` + - SHA-256 Checksum: ``9532d8009cba69b09de9876a0917833a955270d1d8233623b5fbdb18d98e959a`` + - GPG Signature: https://releases.mattermost.com/10.1.2/mattermost-team-10.1.2-linux-amd64.tar.gz.sig + Mattermost Team Edition v10.0.2 - `View Changelog `__ - `Download `__ + - ``https://releases.mattermost.com/10.0.2/mattermost-team-10.0.2-linux-amd64.tar.gz`` + - SHA-256 Checksum: ``d123f16d3569d1f08a5f5d7d102bab2dc155eb7882bb7ce0f95e39264191b21a`` + - GPG Signature: https://releases.mattermost.com/10.0.2/mattermost-team-10.0.2-linux-amd64.tar.gz.sig + Mattermost Team Edition v9.11.4 *Extended Support Release (ESR)* - `View Changelog `__ - `Download `__ + - ``https://releases.mattermost.com/9.11.4/mattermost-team-9.11.4-linux-amd64.tar.gz`` + - SHA-256 Checksum: ``9acec72cfd93e69e10763e13181468b8672563fa0aab9cfd9e87be1d230c7099`` + - GPG Signature: https://releases.mattermost.com/9.11.4/mattermost-team-9.11.4-linux-amd64.tar.gz.sig Mattermost Team Edition v9.10.3 - `View Changelog `__ - `Download `__ - ``https://releases.mattermost.com/9.10.3/mattermost-team-9.10.3-linux-amd64.tar.gz`` - SHA-256 Checksum: ``d50e2d3352129f3eaa5271cb3031b0210f9283954e727f7dca959b4c277ea6fc`` @@ -419,10 +419,10 @@ Version archive - ``https://releases.mattermost.com/9.6.3/mattermost-team-9.6.3-linux-amd64.tar.gz`` - SHA-256 Checksum: ``630a51a8c3228465914b318fd0caa634f1a0a39010482aa478f090efee4ca566`` - GPG Signature: https://releases.mattermost.com/9.6.3/mattermost-team-9.6.3-linux-amd64.tar.gz.sig - Mattermost Team Edition v9.5.11 *Extended Support Release (ESR)* - `View Changelog `__ - `Download `__ - - ``https://releases.mattermost.com/9.5.11/mattermost-team-9.5.11-linux-amd64.tar.gz`` - - SHA-256 Checksum: ``2df79e106e81e4a3d6b0e5ffb40f5821439760a2299d35e6463c9e0a47d5204f`` - - GPG Signature: https://releases.mattermost.com/9.5.11/mattermost-team-9.5.11-linux-amd64.tar.gz.sig + Mattermost Team Edition v9.5.12 *Extended Support Release (ESR)* - `View Changelog `__ - `Download `__ + - ``https://releases.mattermost.com/9.5.12/mattermost-team-9.5.12-linux-amd64.tar.gz`` + - SHA-256 Checksum: ``c00c61173166f586d3503426bd6a93e78005e365d55592a088c36b16105d1876`` + - GPG Signature: https://releases.mattermost.com/9.5.12/mattermost-team-9.5.12-linux-amd64.tar.gz.sig Mattermost Team Edition v9.4.5 - `View Changelog `__ - `Download `__ - ``https://releases.mattermost.com/9.4.5/mattermost-team-9.4.5-linux-amd64.tar.gz`` - SHA-256 Checksum: ``9ab357c21c5d786965f2dc622a109630908b6eacd6412e2d57990e9c92ae19fb`` diff --git a/source/install/download-latest-tarball.rst b/source/install/download-latest-tarball.rst index b8b99be0343..2a64575848b 100644 --- a/source/install/download-latest-tarball.rst +++ b/source/install/download-latest-tarball.rst @@ -9,13 +9,13 @@ Using ``wget``, download the Mattermost Server release you want to install. .. code-block:: sh - wget https://releases.mattermost.com/10.1.1/mattermost-10.1.1-linux-amd64.tar.gz + wget https://releases.mattermost.com/10.1.2/mattermost-10.1.2-linux-amd64.tar.gz .. tab:: Current ESR .. code-block:: sh - wget https://releases.mattermost.com/9.11.3/mattermost-9.11.3-linux-amd64.tar.gz + wget https://releases.mattermost.com/9.11.4/mattermost-9.11.4-linux-amd64.tar.gz .. tab:: Older releases