diff --git a/source/_static/badges/ent-cloud-dedicated.rst b/source/_static/badges/ent-cloud-dedicated.rst new file mode 100644 index 00000000000..56430fc4df0 --- /dev/null +++ b/source/_static/badges/ent-cloud-dedicated.rst @@ -0,0 +1,18 @@ +:orphan: +:nosearch: + +.. raw:: html + +
+ +|plans-img| Available only on `Enterprise `__ plans + +|deployment-img| Available only for `Cloud Dedicated `__ deployments + +.. |plans-img| image:: ../_static/images/badges/flag_icon.svg + +.. |deployment-img| image:: ../_static/images/badges/deployment_icon.svg + +.. raw:: html + +
diff --git a/source/about/editions-and-offerings.rst b/source/about/editions-and-offerings.rst index edb409e9392..b391839527e 100644 --- a/source/about/editions-and-offerings.rst +++ b/source/about/editions-and-offerings.rst @@ -120,7 +120,7 @@ This offering includes all the features of Mattermost Professional, plus: - `Enhanced compliance with global and custom retention policies for messages and files `__. - `Granular administrative control with custom system admin roles `__. - `Advanced configuration of playbook permissions, analytics dashboards, and channel exports `__. -- `Enhanced compliance controls and granular audit logs with data export `__. +- `Enhanced compliance controls and granular audit logs with data export `__. - `Advanced collaboration with shared channels across Mattermost instances `__. - `High availability support with multi-node database deployment `__. - `Horizontal scaling through cluster-based deployment `__. diff --git a/source/comply/audit-log.rst b/source/archive/audit-log.rst similarity index 100% rename from source/comply/audit-log.rst rename to source/archive/audit-log.rst diff --git a/source/collaborate/collaborate-within-embedded-microsoft-teams.rst b/source/collaborate/collaborate-within-embedded-microsoft-teams.rst index 64666090016..33ab8b22d66 100644 --- a/source/collaborate/collaborate-within-embedded-microsoft-teams.rst +++ b/source/collaborate/collaborate-within-embedded-microsoft-teams.rst @@ -9,8 +9,8 @@ The `Mattermost for Microsoft Teams plugin `__, from Doug Lauder, Senior Software Design Engineer at Mattermost, to learn more about using the embedded Mattermost instance within Microsoft Teams: +Check out this `YouTube demo `__, from John Landells, Senior Technical Account Manager at Mattermost, to learn more about using the embedded Mattermost instance within Microsoft Teams: .. raw:: html - \ No newline at end of file + diff --git a/source/comply/embedded-json-audit-log-schema.rst b/source/comply/embedded-json-audit-log-schema.rst index 146b5d26197..a73c843aa66 100644 --- a/source/comply/embedded-json-audit-log-schema.rst +++ b/source/comply/embedded-json-audit-log-schema.rst @@ -1,4 +1,4 @@ -Embedded JSON audit log schema +Audit Log JSON Schema ============================== .. include:: ../_static/badges/ent-selfhosted.rst @@ -81,13 +81,13 @@ JSON data model | | | Mattermost currently supports three log formats: plain, JSON, and `GELF `__. | | | | | | | | - Plain log format uses `RFC3339 `__ by default. | -| | | See the `plain log format configuration `__ documentation for | +| | | See the `plain log format configuration `__ documentation for | | | | supported options. | | | | - JSON log format uses `RFC3339 `__ by default. | -| | | See the `JSON log format configuration `__ documentation for | +| | | See the `JSON log format configuration `__ documentation for | | | | supported options. | | | | - GELF log format uses `unixtime `__. | -| | | See the `GELF log format configuration `__ documentation for | +| | | See the `GELF log format configuration `__ documentation for | | | | supported options. | +------------+------------------------------+-------------------------------------------------------------------------------------------------------------------------------------+ | event_name | string | Unique name and identifier of the event type taking place (e.g. ``getLogs`` ``requestRenewalLink``, | diff --git a/source/conf.py b/source/conf.py index f32e76c11fa..f67e2d5b6c9 100644 --- a/source/conf.py +++ b/source/conf.py @@ -804,6 +804,8 @@ def setup(_: Sphinx): "https://docs.mattermost.com/comply/compliance-monitoring.html", "comply/cloud-data-retention-policy.html": "https://docs.mattermost.com/comply/data-retention-policy.html", +"comply/audit-log.html": + "https://docs.mattermost.com/manage/logging.html", # Configure redirects "configure/config-ssl-http2-apache2.html": @@ -1752,6 +1754,20 @@ def setup(_: Sphinx): "https://docs.mattermost.com/configure/authentication-configuration-settings.html#openid-connect-other-settings", "configure/experimental-configuration-settings.html#enable-app-bar": "https://docs.mattermost.com/configure/experimental-configuration-settings.html#disable-apps-bar", +"configure/experimental-configuration-settings.html#syslog-configuration-options": + "https://docs.mattermost.com/manage/logging.html#syslog-target-configuration-options", +"configure/experimental-configuration-settings.html#syslog-ip": + "https://docs.mattermost.com/manage/logging.html#syslog-target-configuration-options", +"configure/experimental-configuration-settings.html#syslog-port": + "https://docs.mattermost.com/manage/logging.html#syslog-target-configuration-options", +"configure/experimental-configuration-settings.html#syslog-tag": + "https://docs.mattermost.com/manage/logging.html#syslog-target-configuration-options", +"configure/experimental-configuration-settings.html#syslog-cert": + "https://docs.mattermost.com/manage/logging.html#syslog-target-configuration-options", +"configure/experimental-configuration-settings.html#syslog-insecure": + "https://docs.mattermost.com/manage/logging.html#syslog-target-configuration-options", +"configure/experimental-configuration-settings.html#syslog-max-queue-size": + "https://docs.mattermost.com/manage/logging.html#syslog-target-configuration-options", # Deploy redirects "deploy/mobile-apps-faq.html": @@ -3313,7 +3329,7 @@ def setup(_: Sphinx): # General information about the project. project = "Mattermost" -copyright = "2015-2023 Mattermost" +copyright = "2015-2024 Mattermost" author = "Mattermost" # The version info for the project you're documenting, acts as replacement for diff --git a/source/configure/experimental-configuration-settings.rst b/source/configure/experimental-configuration-settings.rst index d38940fe25b..4b470998ceb 100644 --- a/source/configure/experimental-configuration-settings.rst +++ b/source/configure/experimental-configuration-settings.rst @@ -5,8 +5,9 @@ Both self-hosted and Cloud admins can access the following configuration setting - `Experimental System Console configuration settings <#experimental-system-console-configuration-settings>`__ - `Experimental Bleve configuration settings <#experimental-bleve-configuration-settings>`__ -- `Experimental configuration settings for self-hosted deployments only <#experimental-configuration-settings-for-self-hosted-deployments-only>`__ +- `Beta Audit logging configuration settings <#beta-audit-logging-configuration-options>`__ - `Experimental job configuration settings <#experimental-job-configuration-settings>`__ +- `Experimental configuration settings for self-hosted deployments only <#experimental-configuration-settings-for-self-hosted-deployments-only>`__ ---- @@ -743,6 +744,131 @@ Enable Bleve for autocomplete queries ---- +Beta audit logging configuration settings +----------------------------------------- + +Enable the following settings to output audit events. You can specify these settings independently for audit events and AD/LDAP events. +When audit logging is enabled, you can specify size, backup interval, compression, maximium age to manage file rotation, and timestamps for audit logging. + +.. note:: + + These settings aren't available in the System Console and can only be set in ``config.json``. + +.. config:setting:: exp-wroteauditfileslocally + :displayname: File name (Beta Audit Logging) + :systemconsole: N/A + :configjson: FileName + :environment: N/A + :description: Write audit files locally. + +Write audit files locally +~~~~~~~~~~~~~~~~~~~~~~~~~ + +**True**: Audit files are written locally to a file. + +**False**: Audit logs aren't written locally to a file. + ++--------------------------------------------------------------------------------------------------------------------------------------+ +| This feature's ``config.json`` setting is ``".ExperimentalAuditSettings.FileEnabled": false",`` with options ``true`` and ``false``. | ++--------------------------------------------------------------------------------------------------------------------------------------+ + +.. config:setting:: exp-auditfilename + :displayname: File name (Beta Audit Logging) + :systemconsole: N/A + :configjson: FileName + :environment: N/A + :description: Specify the path to the audit file. + +File name +~~~~~~~~~ + +Specify the path to the audit file. + ++-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| This feature's ``config.json`` setting is ``".ExperimentalAuditSettings.FileName": ""`` with string input consisting of a user-defined path (e.g. ``/var/log/mattermost_audit.log``). | ++-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +.. config:setting:: exp-filemaxsize + :displayname: File max size MB (Beta Audit Logging) + :systemconsole: N/A + :configjson: FileMaxSizeMB + :environment: N/A + :description: This is the maximum size (measured in megabytes) that the file can grow before triggering rotation. Default is **100** MB. + +File max size MB +~~~~~~~~~~~~~~~~ + +This is the maximum size (in megabytes) that the file can grow before triggering rotation. The default setting is ``100``. + ++---------------------------------------------------------------------------------------------------------------------+ +| This feature's ``config.json`` setting is ``".ExperimentalAuditSettings.FileMaxSizeMB": 100`` with numerical input. | ++---------------------------------------------------------------------------------------------------------------------+ + +.. config:setting:: exp-filemaxage + :displayname: File max age days (Beta Audit Logging) + :systemconsole: N/A + :configjson: FileMaxAgeDays + :environment: N/A + :description: This is the maximum age in days a file can reach before triggering rotation. The default value is **0**, indicating no limit on the age. + +File max age days +~~~~~~~~~~~~~~~~~ + +This is the maximum age in days a file can reach before triggering rotation. The default value is ``0``, indicating no limit on the age. + ++--------------------------------------------------------------------------------------------------------------------+ +| This feature's ``config.json`` setting is ``".ExperimentalAuditSettings.FileMaxAgeDays": 0`` with numerical input. | ++--------------------------------------------------------------------------------------------------------------------+ + +.. config:setting:: exp-filemaxbackups + :displayname: File max backups (Beta Audit Logging) + :systemconsole: N/A + :configjson: FileMaxBackups + :environment: N/A + :description: This is the maximum number of rotated files kept; the oldest is deleted first. The default value is **0**, indicating no limit on the number of backups. + +File max backups +~~~~~~~~~~~~~~~~ + +This is the maximum number of rotated files kept; the oldest is deleted first. The default value is ``0``, indicating no limit on the number of backups. + ++--------------------------------------------------------------------------------------------------------------------+ +| This feature's ``config.json`` setting is ``".ExperimentalAuditSettings.FileMaxBackups": 0`` with numerical input. | ++--------------------------------------------------------------------------------------------------------------------+ + +.. config:setting:: exp-filecompress + :displayname: File compress (Beta Audit Logging) + :systemconsole: N/A + :configjson: FileCompress + :environment: N/A + :description: When ``true``, rotated files are compressed using ``gzip``. Default value is **false**. + +File compress +~~~~~~~~~~~~~ + +When ``true``, rotated files are compressed using ``gzip``. + ++-------------------------------------------------------------------------------------------------------------------------------------+ +| This feature's ``config.json`` setting is ``".ExperimentalAuditSettings.FileCompress": false`` with options ``true`` and ``false``. | ++-------------------------------------------------------------------------------------------------------------------------------------+ + +.. config:setting:: exp-filemaxqueuesize + :displayname: File max queue size (Beta Audit Logging) + :systemconsole: N/A + :configjson: FileMaxQueueSize + :environment: N/A + :description: This setting determines how many audit records can be queued/buffered at any point in time when writing to a file. Default is **1000** records. + +File max queue size +~~~~~~~~~~~~~~~~~~~ + +This setting determines how many audit records can be queued/buffered at any point in time when writing to a file. The default is ``1000`` records. +This setting can be left as default unless you are seeing audit write failures in the server log and need to adjust the number accordingly. + ++-------------------------------------------------------------------------------------------------------------------------+ +| This feature's ``config.json`` setting is ``".ExperimentalAuditSettings.FileMaxQueueSize": 1000`` with numerical input. | ++-------------------------------------------------------------------------------------------------------------------------+ + Experimental configuration settings for self-hosted deployments only -------------------------------------------------------------------- @@ -939,279 +1065,12 @@ Used to control the buffer of outstanding Push Notification messages to be sent. +---------------------------------------------------------------------------------------------------------------------------------------------+ .. config:setting:: exp-enableauditfiles - :displayname: File configuration options (Experimental) + :displayname: File configuration settings (Beta) :systemconsole: N/A :configjson: FileEnabled :environment: N/A :description: Enable this setting to write audit files locally, specifying size, backup interval, compression, maximum age to manage file rotation, and timestamps. Default value is **false**. -File configuration options -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This setting isn't available in the System Console and can only be set in ``config.json``. - -Enable this setting to write audit files locally, specifying size, backup interval, compression, maximum age to manage file rotation, and timestamps. - -**True**: File output is enabled. - -**False**: File output is disabled. - -+---------------------------------------------------------------------------------------------------------+ -| This feature's ``config.json`` setting is ``"FileEnabled": false`` with options ``true`` and ``false``. | -+---------------------------------------------------------------------------------------------------------+ - -.. config:setting:: exp-auditfilename - :displayname: File name (Experimental) - :systemconsole: N/A - :configjson: FileName - :environment: N/A - :description: This is the path to the output file location. - -File name -~~~~~~~~~ - -This setting isn't available in the System Console and can only be set in ``config.json``. - -This is the path to the output file location. - -+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| This feature's ``config.json`` setting is ``"FileName": ""`` with string input consisting of a user-defined path (e.g. ``/var/log/mattermost_audit.log``). | -+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - -.. config:setting:: exp-filemaxsize - :displayname: File max size MB (Experimental) - :systemconsole: N/A - :configjson: FileMaxSizeMB - :environment: N/A - :description: This is the maximum size (measured in megabytes) that the file can grow before triggering rotation. Default is **100** MB. - -File max size MB -~~~~~~~~~~~~~~~~ - -This setting isn't available in the System Console and can only be set in ``config.json``. - -This is the maximum size (measured in megabytes) that the file can grow before triggering rotation. The default setting is 100. - -+------------------------------------------------------------------------------------------+ -| This feature's ``config.json`` setting is ``"FileMaxSizeMB": 100`` with numerical input. | -+------------------------------------------------------------------------------------------+ - -.. config:setting:: exp-filemaxage - :displayname: File max age days (Experimental) - :systemconsole: N/A - :configjson: FileMaxAgeDays - :environment: N/A - :description: This is the maximum age in days a file can reach before triggering rotation. The default value is **0**, indicating no limit on the age. - -File max age days -~~~~~~~~~~~~~~~~~ - -This setting isn't available in the System Console and can only be set in ``config.json``. - -This is the maximum age in days a file can reach before triggering rotation. The default value is 0, indicating no limit on the age. - -+-----------------------------------------------------------------------------------------+ -| This feature's ``config.json`` setting is ``"FileMaxAgeDays": 0`` with numerical input. | -+-----------------------------------------------------------------------------------------+ - -.. config:setting:: exp-filemaxbackups - :displayname: File max backups - :systemconsole: N/A - :configjson: FileMaxBackups - :environment: N/A - :description: This is the maximum number of rotated files kept; the oldest is deleted first. The default value is **0**, indicating no limit on the number of backups. - -File max backups -~~~~~~~~~~~~~~~~ - -This setting isn't available in the System Console and can only be set in ``config.json``. - -This is the maximum number of rotated files kept; the oldest is deleted first. The default value is 0, indicating no limit on the number of backups. - -+-----------------------------------------------------------------------------------------+ -| This feature's ``config.json`` setting is ``"FileMaxBackups": 0`` with numerical input. | -+-----------------------------------------------------------------------------------------+ - -.. config:setting:: exp-filecompress - :displayname: File compress (Experimental) - :systemconsole: N/A - :configjson: FileCompress - :environment: N/A - :description: When ``true``, rotated files are compressed using ``gzip``. Default value is **false**. - -File compress -~~~~~~~~~~~~~ - -This setting isn't available in the System Console and can only be set in ``config.json``. - -When ``true``, rotated files are compressed using ``gzip``. - -+----------------------------------------------------------------------------------------------------------+ -| This feature's ``config.json`` setting is ``"FileCompress": false`` with options ``true`` and ``false``. | -+----------------------------------------------------------------------------------------------------------+ - -.. config:setting:: exp-filemaxqueuesize - :displayname: File max queue size (Experimental) - :systemconsole: N/A - :configjson: FileMaxQueueSize - :environment: N/A - :description: This setting determines how many audit records can be queued/buffered at any point in time when writing to a file. Default is **1000** records. - -File max queue size -~~~~~~~~~~~~~~~~~~~ - -This setting isn't available in the System Console and can only be set in ``config.json``. - -This setting determines how many audit records can be queued/buffered at any point in time when writing to a file. The default is 1000 records. -This setting can be left as default unless you are seeing audit write failures in the server log and need to adjust the number accordingly. - -+----------------------------------------------------------------------------------------------+ -| This feature's ``config.json`` setting is ``"FileMaxQueueSize": 1000`` with numerical input. | -+----------------------------------------------------------------------------------------------+ - -.. config:setting:: exp-enablesyslog - :displayname: Syslog configuration options (Experimental) - :systemconsole: N/A - :configjson: SysLogEnabled - :environment: N/A - :description: Enable this setting to write audit records to a local or remote syslog, specifying the IP, port, user-generated fields, and certificate settings. Default value is **false**. - -Syslog configuration options -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This setting isn't available in the System Console and can only be set in ``config.json``. - -Enable this setting to write audit records to a local or remote syslog, specifying the IP, port, user-generated fields, and certificate settings. - -**True**: Syslog output is enabled. - -**False**: Syslog output is disabled. - -+-----------------------------------------------------------------------------------------------------------+ -| This feature's ``config.json`` setting is ``"SysLogEnabled": false`` with options ``true`` and ``false``. | -+-----------------------------------------------------------------------------------------------------------+ - -.. config:setting:: exp-syslogip - :displayname: Syslog IP (Experimental) - :systemconsole: N/A - :configjson: SysLogIP - :environment: N/A - :description: The IP address or domain of the syslog server. Default value is **localhost**. - -Syslog IP -~~~~~~~~~ - -This setting isn't available in the System Console and can only be set in ``config.json``. - -The IP address or domain of the syslog server. Use ``localhost`` for local syslog. - -+-------------------------------------------------------------------------------------------------------------------------------------+ -| This feature's ``config.json`` setting is ``"SysLogIP": "localhost"`` with string input consisting of an IP address or domain name. | -+-------------------------------------------------------------------------------------------------------------------------------------+ - -.. config:setting:: exp-syslogport - :displayname: Syslog port (Experimental) - :systemconsole: N/A - :configjson: SysLogPort - :environment: N/A - :description: The port that the syslog server is listening on. Default value is **6514**. - -Syslog port -~~~~~~~~~~~ - -This setting isn't available in the System Console and can only be set in ``config.json``. - -The port that the syslog server is listening on. The default port is 6514. - -+------------------------------------------------------------------------------------------------------------------+ -| This feature's ``config.json`` setting is ``"SysLogPort": 6514`` with numeric input consisting of a port number. | -+------------------------------------------------------------------------------------------------------------------+ - -.. config:setting:: exp-syslogtag - :displayname: Syslog tag (Experimental) - :systemconsole: N/A - :configjson: SysLogTag - :environment: N/A - :description: The syslog metadata tag field. - -Syslog tag -~~~~~~~~~~ - -This setting isn't available in the System Console and can only be set in ``config.json``. - -The syslog metadata tag field. - -+-------------------------------------------------------------------------------------------------------------------------+ -| This feature's ``config.json`` setting is ``"SysLogTag": ""`` with string input consisting of a user-defined tag field. | -+-------------------------------------------------------------------------------------------------------------------------+ - -.. config:setting:: exp-syslogcert - :displayname: Syslog cert (Experimental) - :systemconsole: N/A - :configjson: SysLogCert - :environment: N/A - :description: This is the path to the syslog server certificate for TLS connections (``.crt`` or ``.pem``). - -Syslog cert -~~~~~~~~~~~ - -This setting isn't available in the System Console and can only be set in ``config.json``. - -This is the path to the syslog server certificate for TLS connections (``.crt`` or ``.pem``). - -+-----------------------------------------------------------------------------------------------------------------------------+ -| This feature's ``config.json`` setting is ``"SysLogCert": ""`` with string input consisting of the path to the certificate. | -+-----------------------------------------------------------------------------------------------------------------------------+ - -.. config:setting:: exp-sysloginsecure - :displayname: Syslog insecure (Experimental) - :systemconsole: N/A - :configjson: SysLogInsecure - :environment: N/A - :description: This setting controls whether a client verifies the server's certificate chain and host name. Default value is **false**. - -Syslog insecure -~~~~~~~~~~~~~~~ - -This setting isn't available in the System Console and can only be set in ``config.json``. - -This setting controls whether a client verifies the server's certificate chain and host name. If ``true``, TLS accepts any certificate presented by the server and any host name in that certificate. In this mode, TLS is susceptible to man-in-the-middle attacks. - -.. note:: - This should be used only for testing and not in a production environment. - -+------------------------------------------------------------------------------------------------------------+ -| This feature's ``config.json`` setting is ``"SysLogInsecure": false`` with options ``true`` and ``false``. | -+------------------------------------------------------------------------------------------------------------+ - -.. config:setting:: exp-syslogmaxqueuesize - :displayname: Syslog max queue size (Experimental) - :systemconsole: N/A - :configjson: SysLogMaxQueueSize - :environment: N/A - :description: This setting determines how many audit records can be queued/buffered at any point in time when writing to syslog. Default is **1000** records. - -Syslog max queue size -~~~~~~~~~~~~~~~~~~~~~ - -This setting isn't available in the System Console and can only be set in ``config.json``. - -This setting determines how many audit records can be queued/buffered at any point in time when writing to syslog. The default is 1000 records. -This setting can be left as default unless you are seeing audit write failures in the server log and need to adjust the number accordingly. - -+------------------------------------------------------------------------------------------------+ -| This feature's ``config.json`` setting is ``"SysLogMaxQueueSize": 1000`` with numerical input. | -+------------------------------------------------------------------------------------------------+ - -.. config:setting:: exp-restrictsystemadmin - :displayname: Restrict system admin (Experimental) - :systemconsole: N/A - :configjson: RestrictSystemAdmin - :environment: N/A - - - **true**: Restricts the System Admin from viewing and modifying a subset of server configuration settings from the System Console. - - **false**: **(Default)** No restrictions are applied to the System Admin role. - Restrict system admin ~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/configure/file-storage-configuration-settings.rst b/source/configure/file-storage-configuration-settings.rst index 3cadfc15684..302c0036f5a 100644 --- a/source/configure/file-storage-configuration-settings.rst +++ b/source/configure/file-storage-configuration-settings.rst @@ -125,7 +125,7 @@ Enable document search by content | - **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. | -| - **Justtext**: Used to search HTML 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. | @@ -418,4 +418,4 @@ Amazon S3 request timeout | Amazon S3 storage time out. | - ``config.json`` setting: ``".FileSettings.AmazonS3RequestTimeoutMilliseconds: 30000`` | | | - Environment variable: ``MM_FILESETTINGS_AMAZONS3REQUESTTIMEOUTMILLISECONDS`` | | Default is 30000 (30 seconds). | | -+---------------------------------------------------------------+-----------------------------------------------------------------------------------------+ \ No newline at end of file ++---------------------------------------------------------------+-----------------------------------------------------------------------------------------+ diff --git a/source/configure/logging-configuration-settings.rst b/source/configure/logging-configuration-settings.rst index 87321e8a735..ff935f3aa48 100644 --- a/source/configure/logging-configuration-settings.rst +++ b/source/configure/logging-configuration-settings.rst @@ -13,7 +13,7 @@ Configure logging by going to **System Console > Environment > Logging**, or by - **false**: Output log messages aren’t written to the console. Output logs to console -~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~ *Available in legacy Enterprise Edition E10/E20* @@ -86,6 +86,29 @@ Output console logs as JSON | **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) @@ -118,6 +141,27 @@ Output logs to file | **Note**: Typically set to **true** in a production environment. | +-----------------------------------------------+---------------------------------------------------------------------+ +.. 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 +~~~~~~~~~~~~~~~~~~ + +*Available in legacy Enterprise Edition E10/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 @@ -173,27 +217,6 @@ Output file logs as JSON | **Note**: Typically set to **true** in a production environment. | +-----------------------------------------------+---------------------------------------------------------------------+ -.. 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 -~~~~~~~~~~~~~~~~~~ - -*Available in legacy Enterprise Edition E10/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-enablewebhookdebug :displayname: Enable webhook debugging (Logging) :systemconsole: Environment > Logging @@ -201,7 +224,7 @@ File log directory :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 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 @@ -211,8 +234,8 @@ Enable webhook debugging +-----------------------------------------------+------------------------------------------------------------------------------+ | Configure Mattermost to capture the contents | - System Config path: **Environment > Logging** | -| of incoming webhooks to log files for | - ``config.json setting``: ``".LogSettings.EnableWebhookDebugging": true",`` | -| debugging. | - Environment variable: ``MM_LOGSETTINGS_ENABLEWEBHOOKDEBUGGING`` | +| 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 | | @@ -220,31 +243,9 @@ Enable webhook debugging | - **false**: The contents of incoming | | | webhooks aren’t printed to log files. | | +-----------------------------------------------+------------------------------------------------------------------------------+ - -.. 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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*Available in legacy Enterprise Edition E10/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 `telemetry `__ docummentation for | -| details on the information Mattermost collects. | -+----------------------------------------------+-------------------------------------------------------------------------+ +| **Note**: Enable debug logs by changing the `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) @@ -275,33 +276,9 @@ Output logs to multiple targets | - Logs are recorded asynchronously to reduce latency to the caller. | | - Advanced logging supports hot-reloading of logger configuration. | +-----------------------------------------------+---------------------------------------------------------------------------+ -| **Note**: See the :doc:`audit log v2 ` documentation for additional information. | +| **Note**: See the :doc:`Mattermost logging ` documentation for details. | +-----------------------------------------------+---------------------------------------------------------------------------+ -.. 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-maxfieldsize :displayname: Maximum field size (Logging) :systemconsole: N/A @@ -317,4 +294,29 @@ Maximum field size | log fields during logging. | - ``config.json setting``: ``".LogSettings.MaxFieldSize": 2048",`` | | | - Environment variable: ``MM_LOGSETTINGS_MAXFIELDSIZE`` | | Numerical value. Default is **2048**. | | -+-----------------------------------------------+----------------------------------------------------------------------+ \ No newline at end of file ++-----------------------------------------------+----------------------------------------------------------------------+ + +.. 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +*Available in legacy Enterprise Edition E10/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 `telemetry `__ docummentation for | +| details on the information Mattermost collects. | ++----------------------------------------------+-------------------------------------------------------------------------+ \ No newline at end of file diff --git a/source/configure/reporting-configuration-settings.rst b/source/configure/reporting-configuration-settings.rst index 2f4d26502f9..269f29ffe45 100644 --- a/source/configure/reporting-configuration-settings.rst +++ b/source/configure/reporting-configuration-settings.rst @@ -22,7 +22,7 @@ Site statistics | sessions, commands, webhooks, active users, connections, | - ``config.json setting``: N/A | | and playbooks. | - Environment variable: N/A | +---------------------------------------------------------------+-------------------------------------------------------------+ -| **Note**: Inactive and deactivated users, as well as remote users in | +| **Note**: Deactivated users as well as synthetic users in | | `Microsoft Teams integrations `__ | | and `shared channels users `__, aren't counted towards the total number of active users. | +---------------------------------------------------------------+-------------------------------------------------------------+ @@ -39,7 +39,7 @@ Team statistics | number of public and private channels, total post count, and | - ``config.json`` setting: N/A | | count of paid users (self-hosted only). | - Environment variable: N/A | +---------------------------------------------------------------+---------------------------------------------------------------+ -| **Note**: Inactive and deactivated users are not counted towards the total number of active users. | +| **Note**: Deactivated users are not counted towards the total number of active users. | +---------------------------------------------------------------+---------------------------------------------------------------+ ---- diff --git a/source/deploy/legacy-self-hosted-changelog.md b/source/deploy/legacy-self-hosted-changelog.md index a823b0128e7..d1ada9fb7f8 100644 --- a/source/deploy/legacy-self-hosted-changelog.md +++ b/source/deploy/legacy-self-hosted-changelog.md @@ -18,6 +18,10 @@ From Mattermost v9.2, see the [Mattermost Changelog](/deploy/mattermost-changelo ## Release v9.1 - [Feature Release](https://docs.mattermost.com/upgrade/release-definitions.html#feature-release) +- **9.1.5, released 2024-01-09** + - Mattermost v9.1.5 contains 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/). + - Mattermost v9.1.5 contains the following functional changes: + - Fixed an issue where invalid reactions could be added to posts. Added default limit of the number of reactions per post. - **9.1.4, released 2023-11-29** - Mattermost v9.1.4 contains 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/). - Mattermost v9.1.4 contains no database or functional changes. @@ -267,6 +271,12 @@ Multiple setting options were added to ``config.json``. Below is a list of the a ## Release v8.1 - [Extended Support Release](https://docs.mattermost.com/upgrade/release-definitions.html#extended-support-release-esr) +- **8.1.8, released 2024-01-09** + - Mattermost v8.1.8 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 double URL encoding of Oauth redirect URI params. + - Pre-packaged Jira plugin version [v4.0.1](https://github.com/mattermost/mattermost-plugin-jira/releases/tag/v4.0.1). Also see [v4.0.0](https://github.com/mattermost/mattermost-plugin-jira/releases/tag/v4.0.0) for recent breaking changes. + - Mattermost v8.1.8 contains the following functional changes: + - Fixed an issue where invalid reactions could be added to posts. Added default limit of the number of reactions per post. - **8.1.7, released 2023-11-29** - Mattermost v8.1.7 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/). - Mattermost v8.1.7 contains no database or functional changes. diff --git a/source/deploy/mattermost-changelog.md b/source/deploy/mattermost-changelog.md index 0d402592abf..acc6b5fc19e 100644 --- a/source/deploy/mattermost-changelog.md +++ b/source/deploy/mattermost-changelog.md @@ -119,6 +119,10 @@ See [this walkthrough video](https://www.youtube.com/watch?v=eXA8emM97Bo) on som ## Release v9.2 - [Feature Release](https://docs.mattermost.com/upgrade/release-definitions.html#feature-release) +- **9.2.4, released 2024-01-09** + - Mattermost v9.2.4 contains 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/). + - Mattermost v9.2.4 contains the following functional changes: + - Fixed an issue where invalid reactions could be added to posts. Added default limit of the number of reactions per post. - **9.2.3, released 2023-11-29** - Mattermost v9.2.3 contains 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/). - Mattermost v9.2.3 contains no database or functional changes. diff --git a/source/guides/cloud-workspace-management.rst b/source/guides/cloud-workspace-management.rst index 8fd61fae46a..b9b635bfc7f 100644 --- a/source/guides/cloud-workspace-management.rst +++ b/source/guides/cloud-workspace-management.rst @@ -15,3 +15,4 @@ Cloud workspace management * :doc:`Workspace usage ` - Keep your workspace active. * :doc:`Workspace migration ` - Migrate your workspace using the mmctl tool. * :doc:`Cloud data residency ` - Find information about your data in the Cloud. +* :doc:`Cloud Bring Your Own Key (BYOK) ` - Learn how to manage data encryption processes within a Mattermost Cloud Enterprise Dedicated deployment. diff --git a/source/guides/self-hosted-administration.rst b/source/guides/self-hosted-administration.rst index 329199d211a..9b4ce60a1f6 100644 --- a/source/guides/self-hosted-administration.rst +++ b/source/guides/self-hosted-administration.rst @@ -21,7 +21,7 @@ This section of the guide is for system admins of self-hosted Mattermost servers Migration from MySQL to PostgreSQL Chinese, Japanese, and Korean search Customize Mattermost - Audit logging + Mattermost logging JSON audit log schema SSL client certificate setup Certificate-based authentication @@ -40,7 +40,7 @@ This section of the guide is for system admins of self-hosted Mattermost servers * :doc:`Migration guidelines from MySQL to PostgreSQL ` - Learn how to migrate the Mattermost database from MySQL to PostgreSQL. * :doc:`Chinese, Japanese, and Korean search ` - Set up search capabilities for teams communicating via Chinese, Japanese, or Korean. * :doc:`Whitelabel Mattermost ` - Whitelabel the Mattermost server and apps. -* :doc:`Audit logging ` - Learn how Mattermost records activities and events performed within a Mattermost workspace. +* :doc:`Mattermost logging ` - Learn how Mattermost records activities and events performed within a Mattermost workspace. * :doc:`JSON audit log schema ` - Learn how to configure Mattermost audit logging using a JSON object. * :doc:`SSL client certificate setup ` - Configure SSL client certificates for Mattermost Desktop and Web Apps. * :doc:`Certificate-Based Authentication ` - Set up certificate-based authentication for Mattermost. diff --git a/source/images/keycloak_1_client_settings.png b/source/images/keycloak_1_client_settings.png index b340ff381fe..6a0546206ef 100644 Binary files a/source/images/keycloak_1_client_settings.png and b/source/images/keycloak_1_client_settings.png differ diff --git a/source/images/keycloak_2_saml_keys.png b/source/images/keycloak_2_saml_keys.png index 55c4fedba45..5cb19c5590e 100644 Binary files a/source/images/keycloak_2_saml_keys.png and b/source/images/keycloak_2_saml_keys.png differ diff --git a/source/images/keycloak_3_add_builtins.png b/source/images/keycloak_3_add_builtins.png index 7e08e018e9d..d638da78d63 100644 Binary files a/source/images/keycloak_3_add_builtins.png and b/source/images/keycloak_3_add_builtins.png differ diff --git a/source/images/keycloak_4_create_username_attribute.png b/source/images/keycloak_4_create_username_attribute.png index c486904ba75..8921fa32a4b 100644 Binary files a/source/images/keycloak_4_create_username_attribute.png and b/source/images/keycloak_4_create_username_attribute.png differ diff --git a/source/images/keycloak_4_create_username_attribute_finished.png b/source/images/keycloak_4_create_username_attribute_finished.png index 7d6d81ce933..0c2b7c771fc 100644 Binary files a/source/images/keycloak_4_create_username_attribute_finished.png and b/source/images/keycloak_4_create_username_attribute_finished.png differ diff --git a/source/images/keycloak_9_export_metadata.png b/source/images/keycloak_9_export_metadata.png index b9a882f659a..9bb35a28dc7 100644 Binary files a/source/images/keycloak_9_export_metadata.png and b/source/images/keycloak_9_export_metadata.png differ diff --git a/source/install/download-latest-tarball.rst b/source/install/download-latest-tarball.rst index 4febd48d0f5..b50ecd7dca5 100644 --- a/source/install/download-latest-tarball.rst +++ b/source/install/download-latest-tarball.rst @@ -35,7 +35,7 @@ Using ``wget``, download the Mattermost Server release you want to install.
- wget https://releases.mattermost.com/8.1.7/mattermost-8.1.7-linux-amd64.tar.gz + wget https://releases.mattermost.com/8.1.8/mattermost-8.1.8-linux-amd64.tar.gz Copied to clipboard
diff --git a/source/install/install-kubernetes.rst b/source/install/install-kubernetes.rst index 2be5da19291..467aff62131 100644 --- a/source/install/install-kubernetes.rst +++ b/source/install/install-kubernetes.rst @@ -11,7 +11,7 @@ Install Mattermost on Kubernetes You can install and deploy a production-ready Mattermost system on a Kubernetes cluster using the Mattermost Kubernetes Operator in practically any environment with less IT overhead and more automation. -You'll need a `Kubernetes cluster `__ running version 1.16 or higher, Kubernetes CLI `kubectl `__ installed on local machine, and a basic understanding of Kubernetes concepts (such as deployments, pods) and actions (such as applying manifests, viewing pod logs). Running Mattermost in Kubernetes requires resources based on your total number of users. See the `Mattermost Kubernetes Operator `__ documentation to learn more about the minimum Kubernetes cluster resources Mattermost requires at different scales. +You'll need a `Kubernetes cluster `__ running `a version that is currently supported with patch releases `__, Kubernetes CLI `kubectl `__ installed on local machine, and a basic understanding of Kubernetes concepts (such as deployments, pods) and actions (such as applying manifests, viewing pod logs). Running Mattermost in Kubernetes requires resources based on your total number of users. See the `Mattermost Kubernetes Operator `__ documentation to learn more about the minimum Kubernetes cluster resources Mattermost requires at different scales. .. tip:: @@ -48,10 +48,10 @@ Deploy Mattermost apiVersion: v1 kind: Secret metadata: - name: mattermost-license + name: my-mattermost-license type: Opaque stringData: - license: [LICENSE_FILE_CONTENTS] + license: 2. Create an installation manifest file locally in a text editor by copying and pasting contenst from the Mattermost installation manifest, and adjusting fields for your configuration and environment. @@ -60,37 +60,34 @@ Deploy Mattermost apiVersion: installation.mattermost.com/v1beta1 kind: Mattermost metadata: - name: mm-example-full # Chose the desired name + name: # Chose the desired installation name. Example = mm-example-full spec: - size: 5000users # Adjust to your requirements + size: # Adjust to your requirements. Example = 5000users ingress: enabled: true - host: example.mattermost-example.com # Adjust to your domain + host: # Adjust to your domain. Example = example.mattermost-example.com annotations: kubernetes.io/ingress.class: nginx - version: 6.0.1 - licenseSecret: "" # If you have created secret in step 1, put its name here + version: # Select a recent supported version of Mattermost. Example = 9.3.0 + licenseSecret: "" # If you created a license secret in step 1, put the secret name here Save the file as ``mattermost-installation.yaml``. While recommended file names are provided, your naming conventions may differ. Some of the most commonly-used fields include: .. csv-table:: - :header: "Field", "Description", "Must Edit" - - "metadata.name", "The name of your Mattermost as it will be shown in Kubernetes. The shorter the better.", "Yes" - "spec.size", "The size of your installation. This can be '100users', '1000users, '5000users', '10000users', or '25000users'.", "Yes" - "spec.ingress.host", "The DNS for your Mattermost installation.", "Yes" - "spec.version", "The Mattermost version.", "No" - "spec.licenseSecret", "The name of the Kubernetes secret containing your license (e.g. mattermost-license). Required for Enterprise deployments.", "No" - "spec.mattermostEnv", "List of custom environment variables for the Mattermost instance.", "No" + :header: "Field", "Description" + + "metadata.name", "The name of your Mattermost as it will be shown in Kubernetes. The shorter the better." + "spec.size", "The size of your installation. This can be '100users', '1000users, '5000users', '10000users', or '25000users'." + "spec.ingress.host", "The DNS for your Mattermost installation." + "spec.version", "The Mattermost version. Refer to `the version archive page `__ when selecting a mattermost version." + "spec.licenseSecret", "The name of the Kubernetes secret containing your license (e.g. mattermost-license). Required for Enterprise deployments." + "spec.mattermostEnv", "List of custom environment variables for the Mattermost instance. Only required when tweaking Mattermost configuration is required." - Additional fields are documented `in the example `__. - If you have previous experience with Kubernetes Custom Resources, you can also check the `Custom Resource Definition `__. + Additional fields are documented `in the example `__. If you have previous experience with Kubernetes Custom Resources, you can also check the `Custom Resource Definition `__. -3. Create external database secret. - - The database secret needs to be created in the namespace that will hold the Mattermost installation. The secret should contain the following data: +3. Create external database secret. The database secret needs to be created in the namespace that will hold the Mattermost installation. The secret should contain the following data: .. csv-table:: :header: "Key", "Description", "Required" @@ -115,11 +112,9 @@ Deploy Mattermost .. note:: - - For PostgreSQL databases, the connection is checked with `pg_isready `__ so the ``DB_CONNECTION_CHECK_URL`` is the same as connection string. - -4. Create external filestore secret. + For PostgreSQL databases, the connection is checked with `pg_isready `__ so the ``DB_CONNECTION_CHECK_URL`` is the same as connection string. - The filestore secret needs to be created in the namespace that will hold the Mattermost installation. The secret should contain the following data: +4. Create external filestore secret. The filestore secret needs to be created in the namespace that will hold the Mattermost installation. The secret should contain the following data: .. csv-table:: :header: "Key", "Description", "Required" @@ -192,8 +187,8 @@ Deploy Mattermost host: example.mattermost-example.com annotations: kubernetes.io/ingress.class: nginx - version: 6.0.1 - licenseSecret: "" + version: 9.3.0 + licenseSecret: my-mattermost-license database: external: secret: my-postgres-connection @@ -210,7 +205,7 @@ Deploy Mattermost 6. Apply the installation manifest file. Manifests are applied with ``kubectl``. Before running the commands make sure you are connected to your Kubernetes cluster. - a. Create the Mattermost namespace: + a. Create a namespace for this new Mattermost installation: .. code-block:: sh :class: mm-code-block diff --git a/source/install/install-ubuntu.rst b/source/install/install-ubuntu.rst index c5460e09e54..3937f57284a 100644 --- a/source/install/install-ubuntu.rst +++ b/source/install/install-ubuntu.rst @@ -148,7 +148,7 @@ When a new Mattermost version is released, run: ``sudo apt update && sudo apt up .. note:: - When you run the ``sudo apt uprade`` command, ``mattermost-server`` will be updated along with any other packages. We strongly recommend you stop the Mattermost Server before running the ``apt`` command using ``sudo systemctl stop mattermost-server``. + When you run the ``sudo apt upgrade`` command, ``mattermost-server`` will be updated along with any other packages. We strongly recommend you stop the Mattermost Server before running the ``apt`` command using ``sudo systemctl stop mattermost-server``. Remove Mattermost ------------------ @@ -164,4 +164,4 @@ Frequently asked questions -------------------------- .. include:: common-deploy-faq.rst - :start-after: :nosearch: \ No newline at end of file + :start-after: :nosearch: diff --git a/source/manage/cloud-byok.rst b/source/manage/cloud-byok.rst new file mode 100644 index 00000000000..57de32f9499 --- /dev/null +++ b/source/manage/cloud-byok.rst @@ -0,0 +1,81 @@ +Cloud Dedicated Bring Your Own Key +=================================== + +.. include:: ../_static/badges/ent-cloud-dedicated.rst + :start-after: :nosearch: + +Bring Your Own Key (BYOK) provides Enterprise Cloud customers with autonomy over their encryption key life cycle. BYOK supports encryption at rest with custom KMS keys that the enterprise provides and maintains. + +BYOK requires a subscription to Mattermost Cloud Enterprise Dedicated, which offers enhanced data security and compliance by ensuring that enterprises have full control over their data encryption processes. + +In Mattermost Cloud Enterprise Dedicated, you can use KMS keys in 2 ways: + +- One KMS key for all services; or, +- Per-service KMS keys (EBS, RDS, S3) + - Keys do not need to be unique to each service. + - All services must be encrypted at rest. + - Selective enablement of this feature can be supported. + - In cases where a global database is needed, we recommend providing 2 KMS keys (1 per region). + +Configure BYOK +------------------------ +1. Enterprise customer provides their AWS KMS ARN to the Mattermost Infrastructure SRE team. +2. Enterprise customer adds the following blocks to their KMS Policy for the AWS KMS ARN provided: + +.. code-block:: JSON + + { + "Sid": "Allow use of the key", + "Effect": "Allow", + "Principal": { + "AWS": "arn:aws:iam:::user/mattermost-cloud--provisioning-" + }, + "Action": [ + "kms:Encrypt", + "kms:Decrypt", + "kms:ReEncrypt*", + "kms:GenerateDataKey*", + "kms:DescribeKey" + ], + "Resource": "" + }, + { + "Sid": "Allow use of the key role nodes", + "Effect": "Allow", + "Principal": { + "AWS": "arn:aws:iam:::role/nodes.-kops.k8s.local" + }, + "Action": [ + "kms:Encrypt", + "kms:Decrypt", + "kms:ReEncrypt*", + "kms:GenerateDataKey*", + "kms:DescribeKey" + ], + "Resource": "" + }, + +3. The Mattermost Infrastructure SRE team updates the kops cluster and S3, RDS resources after the KMS policy is updated on the customer's end. + +Alternatively, the Enterprise customer can provide an external key (non-KMS) to the Mattermost Infrastructure SRE team that Mattermost maintains on behalf of the customer. +This path offers less control to customers but simplifies the setup process. + +Requirements +~~~~~~~~~~~~~~~~~~~~~~~ + +- Customers must own their AWS Account. (In the alternative path mentioned above this is delegated to Mattermost.) +- Customers oversee the maintenance life cycle of their custom KMS key. +- A valid AWS KMS ARN for encrypting storage and databases should be provided to the Infrastructure SRE team. +- The customer should incorporate the provided policy blocks from the Infrastructure SRE team into their KMS key policy. + +Considerations +~~~~~~~~~~~~~~~~~~~~~~~ +- Changing the AWS KMS key in the database necessitates downtime due to AWS Aurora's encryption `limitations. `__ +- Proper communication is essential for setting expectations and scheduling changes. + +Conclusion +-------------- + +If you are a large enterprise with compliance requirements, or are working in highly-regulated industries, using Mattermost Cloud Dedicated with BYOK ensures full data control. + +For any further assistance or queries, `contact our support team `__. diff --git a/source/manage/logging.rst b/source/manage/logging.rst new file mode 100644 index 00000000000..e46049aedb5 --- /dev/null +++ b/source/manage/logging.rst @@ -0,0 +1,489 @@ +Mattermost logging +=================== + +.. include:: ../_static/badges/allplans-cloud-selfhosted.rst + :start-after: :nosearch: + +.. contents:: On this page + :depth: 2 + +By default, Mattermost writes logs to both the console and to the ``mattermost.log`` file in a machine-readable JSON format. + +You can customize the following logging options based on your business practices and needs by going to **System Console > Environment > Logging** or by editing the ``config.json`` file directly: + + +Console logs +------------ + +Console logs feature verbose debug level log messages written to the console using the standard output stream (stdout). + +Customize the following console logs by going to **System Console > Environment > Logging** or by editing the ``config.json`` file directly: + +- `Stop outputting console logs `__ +- `Adjust console log level `__ +- `Output console logs as plain text `__ & `colorize plain text log level details `__ +- `Omit webhook debug messages `__ + +File logs +--------- + +File logs feature info level log messages including errors and information around startup and initialization and webhook debug messages. The file is stored in ``./logs/mattermost.log``, rotated at 100 MB, and archived to a separate file in the same directory. + +Customize the following file logs by going to **System Console > Environment > Logging** or by editing the ``config.json`` file directly: + +- `Stop outputting file logs `__ +- `Adjust file log level `__ +- `Output file logs as plain text `__ +- `Change where the file is stored `__ + +You can optionally output log records to any combination of `console <#console-target-configuration-options>`__, `local file <#file-target-configuration-options>`__, `syslog <#syslog-target-configuration-options>`__, and `TCP socket <#tcp-target-configuration-options>`__ targets, each featuring additional customization. See `Advanced Logging <#advanced-logging>`__ for details. + +Define logging output +--------------------- + +Define logging output in JSON format in the System Console by going to **Environment > Logging > Advanced Logging** or by editing the ``config.json`` file directly. You can use the sample JSON below as a starting point. + +.. code-block:: JSON + + { + "console1": { + "Type": "console", + "Format": "json", + "Levels": [ + {"ID": 5, "Name": "debug", "Stacktrace": false}, + {"ID": 4, "Name": "info", "Stacktrace": false, "color": 36}, + {"ID": 3, "Name": "warn", "Stacktrace": false}, + {"ID": 2, "Name": "error", "Stacktrace": true, "color": 31}, + {"ID": 1, "Name": "fatal", "Stacktrace": true, "color": 31}, + {"ID": 0, "Name": "panic", "Stacktrace": true, "color": 31}, + {"ID": 10, "Name": "stdlog", "Stacktrace": false} + ], + "Options": { + "Out": "stdout" + }, + "MaxQueueSize": 1000 + }, + "file1": { + "Type": "file", + "Format": "json", + "Levels": [ + {"ID": 5, "Name": "debug", "Stacktrace": false}, + {"ID": 4, "Name": "info", "Stacktrace": false}, + {"ID": 3, "Name": "warn", "Stacktrace": false}, + {"ID": 2, "Name": "error", "Stacktrace": true}, + {"ID": 1, "Name": "fatal", "Stacktrace": true}, + {"ID": 0, "Name": "panic", "Stacktrace": true} + ], + "Options": { + "Compress": true, + "Filename": "mattermost_logging.log", + "MaxAgeDays": 1, + "MaxBackups": 10, + "MaxSizeMB": 100 + }, + "MaxQueueSize": 1000 + }, + "file2": { + "Type": "file", + "Format": "json", + "Levels": [ + {"ID": 2, "Name": "error", "Stacktrace": true}, + {"ID": 1, "Name": "fatal", "Stacktrace": true}, + {"ID": 0, "Name": "panic", "Stacktrace": true} + ], + "Options": { + "Compress": true, + "Filename": "mattermost_logging_errors.log", + "MaxAgeDays": 30, + "MaxBackups": 10, + "MaxSizeMB": 100 + }, + "MaxQueueSize": 1000 + } + } + +---- + +Audit logging (Beta) +----------------------------- + +.. include:: ../_static/badges/ent-only.rst + :start-after: :nosearch: + +By default, Mattermost doesn’t write audit logs locally to a file on the server. You can enable and customize experimental audit logging in Mattermost to record activities and events performed within a Mattermost workspace, such as access to the Mattermost REST API or mmctl. + +.. tip:: + From Mattermost v9.3, you can enable and customize advanced logging for AD/LDAP events separately from other logging. + +- Logs are recorded asynchronously to reduce latency to the caller, and are stored separately from general logging. +- During short spans of inability to write to targets, the audit records buffer in memory with a configurable maximum record cap. Based on typical audit record volumes, it could take many minutes to fill the buffer. After that, the records are dropped, and the record drop event is logged. + +You can define `whether audit events are output to file `__, `the name and path of the audit logging file `__, the `maximum size of each file `__, the `maximum number of days before triggering a rotation `__, the `maximum number of rotated files to keep `__, `whether files are compressed using GZIP `__, and `how many audit records can be queued/buffered `__ at any point in time when writing to a file. + +In addition, you can output audit log records to any combination of `console <#console-target-configuration-options>`__, `local file <#file-target-configuration-options>`__, `syslog <#syslog-target-configuration-options>`__, and `TCP socket <#tcp-target-configuration-options>`__ targets, each featuring additional customization. See `Advanced Logging <#advanced-logging>`__ for details. + +.. warning:: + + - From Mattermost v7.2, experimental audit logging beta is a breaking change from previous releases in cases where customers looking to parse previous audit logs with the new format. + - The format and content of an audit log record has changed to become standardized for all events using a `standard JSON schema `__. + - Existing tools which ingest or parse audit log records may need to be modified. + +---- + +Advanced logging +----------------- + +.. include:: ../_static/badges/ent-only.rst + :start-after: :nosearch: + +System admins can output log and audit records to any combination of `console <#console-target-configuration-options>`__, `local file <#file-target-configuration-options>`__, `syslog <#syslog-target-configuration-options>`__, and `TCP socket <#tcp-target-configuration-options>`__ targets. Each output target features additional configuration options you can customize for your Mattermost deployment. + +.. tip:: + + - From Mattermost v9.3, system admins can configure advanced logging options in the System Console using multi-line JSON by going to **Environment > Logging**. + - Alternatively, admins can configure advanced logging within the ``AdvancedLoggingJSON`` section of the ``config.json`` file using multi-line JSON or escaped JSON as a string. + - Mattermost Team Edition customers can output audit log records to the console or a file. + +Advanced logging options can be configured to: + +- Enable trace logging for AD/LDAP to troubleshoot authentication issues. +- Capture errors and panics in a separate, monitored file that triggers alerts. +- Capture production debug and error logs in a separate file with log file rotation to reproduce issues, while enforcing a cap on the amount of disk space the debug logs are allowed to use. +- Audit every API endpoint accessed during a user workflow. + +Configuring advanced logging includes the following steps: + +- `Define log output <#define-audit-log-output>`__ as multi-line JSON or a filespec to another configuration file. +- `Specify destination targets <#specify-destination-targets>`__, including any combination of `console <#console-target-configuration-options>`__, `local file <#file-target-configuration-options>`__, `syslog <#syslog-target-configuration-options>`__, and `TCP socket <#tcp-target-configuration-options>`__ targets. +- `Configure format preferences <#specify-destination-targets>`__ for `plain <#plain-log-format-configuration-options>`__, `JSON <#json-log-format-configuration-options>`__, or `GELF <#gelf-log-format-configuration-options>`__ output. +- `Configure log levels & events <#configure-log-levels-and-events>`__ +- `Configure target-specific settings <#configure-target-specific-settings>`__ + +Define advanced log output +~~~~~~~~~~~~~~~~~~~~~~~ + +.. tabs:: + + .. tab:: Multi-line JSON + + In the example below, file output is written to ``./logs/audit.log`` in plain text and includes all audit log levels & events. Older logs are kept for 1 day, and up to a total of 10 backup log files are kept at a time. Logs are rotated using gzip when the maximum size of the log file reaches 500 MB. A maximum of 1000 audit records can be queued/buffered while writing to the file. + + .. code-block:: JSON + + "AdvancedLoggingJSON": { + "file_1": { + "Type": "file", + "Format": "plain", + "Levels": [ + { "id": 100, "name": "audit-api" }, + { "id": 101, "name": "audit-content" }, + { "id": 102, "name": "audit-permissions" }, + { "id": 103, "name": "audit-cli" } + ], + "Options": { + "Compress": true, + "Filename": "./logs/audit.log", + "MaxAgeDays": 1, + "MaxBackups": 10, + "MaxSizeMB": 500 + }, + "MaxQueueSize": 1000 + } + } + + .. tab:: Filespec + + Advanced logging configuration can be pointed to a filespec to another configuration file, rather than multi-line JSON, to keep the config.json file tidy: + + .. code:: JSON + + "AdvancedLoggingJSON": "/path/to/audit_log_config.json" + + The separate configuration file includes the multi-line JSON instead. + + In the example below, the first output is written to the console in plain text and includes all audit log levels, events, and command outputs. A pipe ``|`` delimiter is placed between fields. + + A second output is written to ``./logs/audit.log`` in plain text in a machine-readable JSON format and includes all audit log levels, events, and command outputs. Older logs are kept for 1 day, and up to a total of 10 backup log files are kept at a time. Logs are rotated using GZIP when the maximum size of the log file reaches 500 MB. A maximum of 1000 audit records can be queued/buffered while writing to the file. + + Contents of ``audit_log_config.json`` file: + + .. code-block:: JSON + + { + "sample-console": { + "type": "console", + "format": "plain", + "format_options": { + "delim": " | " + }, + "levels": [ + { "id": 100, "name": "audit-api" }, + { "id": 101, "name": "audit-content" }, + { "id": 102, "name": "audit-permissions" }, + { "id": 103, "name": "audit-cli" } + ], + "options": { + "out": "stdout" + }, + "maxqueuesize": 1000 + }, + "sample-file": { + "type": "file", + "format": "json", + "levels": [ + { "id": 100, "name": "audit-api" }, + { "id": 101, "name": "audit-content" }, + { "id": 102, "name": "audit-permissions" }, + { "id": 103, "name": "audit-cli" } + ], + "options": { + "compress": true, + "filename": "./logs/audit.log", + "max_age": 1, + "max_backups": 10, + "max_size": 500 + }, + "maxqueuesize": 1000 + } + } + +Specify destination targets +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Log records can be sent to any combination of `console <#console-target-configuration-options>`__, `local file <#file-target-configuration-options>`__, `syslog <#syslog-target-configuration-options>`__, and `TCP socket <#tcp-target-configuration-options>`__ targets. Log targets have been chosen based on support for the vast majority of log aggregators and other log analysis tools, without needing additional software installed. + +System Admins can define multiple log targets to: + +- Mirror log output to files and log aggregators for redundancy. +- Log certain entries to specific destinations. For example, all ``audit-content`` records can be routed to a different destination than the other levels. +- Admins can also temporarily disable log targets by setting its ``type`` to ``none``. + +Configure format preferences +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +System admins can control log formatting per target. + +Plain log format configuration options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + ++---------------------+----------+------------------------------------------------------------------------------------------------------------------------------+ +| **Key** | **Type** | **Description** | ++---------------------+----------+------------------------------------------------------------------------------------------------------------------------------+ +| disable_timestamp | bool | Disables output of the timestamp. Default is ``false``. | ++---------------------+----------+------------------------------------------------------------------------------------------------------------------------------+ +| disable_level | bool | Disables output of the level name. Default is ``false``. | ++---------------------+----------+------------------------------------------------------------------------------------------------------------------------------+ +| disable_msg | bool | Disables output of the message text. Default is ``false``. | ++---------------------+----------+------------------------------------------------------------------------------------------------------------------------------+ +| disable_fields | bool | Disables output of all fields. Default is ``false``. | ++---------------------+----------+------------------------------------------------------------------------------------------------------------------------------+ +| disables_stacktrace | bool | Disables output of stack traces. Default is ``false``. | ++---------------------+----------+------------------------------------------------------------------------------------------------------------------------------+ +| delim | string | Delimiter placed between fields. Default is single space. | ++---------------------+----------+------------------------------------------------------------------------------------------------------------------------------+ +| min_level_len | number | Minimum level name length. When level names are less than the minimum, level names are padded with spaces. Default is ``0``. | ++---------------------+----------+------------------------------------------------------------------------------------------------------------------------------+ +| min_msg_len | number | Minimum message length. When message text is less than the minimum, message text is padded with spaces. Default is ``0``. | ++---------------------+----------+------------------------------------------------------------------------------------------------------------------------------+ +| timestamp_format | string | Format for timestamps. Default is `RFC3339 `__. | ++---------------------+----------+------------------------------------------------------------------------------------------------------------------------------+ +| line_end | string | Alternative end of line character(s). Default is ``n``. | ++---------------------+----------+------------------------------------------------------------------------------------------------------------------------------+ +| enable_color | bool | Enables color for targets that support color output. Default is ``false``. | ++---------------------+----------+------------------------------------------------------------------------------------------------------------------------------+ + +JSON log format configuration options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + ++---------------------+----------+-----------------------------------------------------------------------------------------+ +| **Key** | **Type** | **Description** | ++---------------------+----------+-----------------------------------------------------------------------------------------+ +| disable_timestamp | bool | Disables output of the timestamp. Default is ``false``. | ++---------------------+----------+-----------------------------------------------------------------------------------------+ +| disable_level | bool | Disables output of the log level display name. Default is ``false``. | ++---------------------+----------+-----------------------------------------------------------------------------------------+ +| disable_msg | bool | Disables output of the message text. Default is ``false``. | ++---------------------+----------+-----------------------------------------------------------------------------------------+ +| disable_fields | bool | Disables output of all fields. Default is ``false``. | ++---------------------+----------+-----------------------------------------------------------------------------------------+ +| disables_stacktrace | bool | Disables output of stack traces. Default is ``false``. | ++---------------------+----------+-----------------------------------------------------------------------------------------+ +| timestamp_format | string | Format for timestamps. Default is `RFC3339 `__. | ++---------------------+----------+-----------------------------------------------------------------------------------------+ + +GELF log format configuration options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + ++----------+----------+----------------------------------------------------------+ +| **Key** | **Type** | **Description** | ++----------+----------+----------------------------------------------------------+ +| hostname | string | Outputs a custom hostname in log records. | +| | | If omitted, hostname is taken from the operating system. | ++----------+----------+----------------------------------------------------------+ + +Configure log levels and events +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++------------+----------+--------------------------------------------------------------+ +| **Key** | **Type** | **Description** | ++------------+----------+--------------------------------------------------------------+ +| id | number | Unique identifier of the log level. | ++------------+----------+--------------------------------------------------------------+ +| name | string | Name of the log level. | ++------------+----------+--------------------------------------------------------------+ +| stacktrace | bool | Outputs a stack trace. Default is ``false``. | ++------------+----------+--------------------------------------------------------------+ +| color | number | The ANSI color code used to output parts of the log record. | +| | | Supported values include: | +| | | | +| | | - Black: ``30`` | +| | | - Red: ``31`` | +| | | - Green: ``32`` | +| | | - Yellow: ``33`` | +| | | - Blue: ``34`` | +| | | - Magenta: ``35`` | +| | | - Cyan: ``36`` | +| | | - White: ``37`` | ++------------+----------+--------------------------------------------------------------+ + +Log levels +^^^^^^^^^^ + ++--------+-----------------------+--------------------------------------------------------------------------+ +| **ID** | **Name** | **Description** | ++--------+-----------------------+--------------------------------------------------------------------------+ +| 100 | ``audit-api`` | API events | ++--------+-----------------------+--------------------------------------------------------------------------+ +| 101 | ``audit-content`` | Content changes. This log level can generate considerably more records | +| | | than the other audit log levels. | ++--------+-----------------------+--------------------------------------------------------------------------+ +| 102 | ``audit-permissions`` | Permission changes | ++--------+-----------------------+--------------------------------------------------------------------------+ +| 103 | ``audit-cli`` | CLI operations | ++--------+-----------------------+--------------------------------------------------------------------------+ +| 140 | ``LDAPError`` | AD/LDAP authentication errors | ++--------+-----------------------+--------------------------------------------------------------------------+ +| 141 | ``LDAPWarn`` | AD/LDAP authentication warnings | ++--------+-----------------------+--------------------------------------------------------------------------+ +| 142 | ``LDAPInfo`` | AD/LDAP authentication information logs | ++--------+-----------------------+--------------------------------------------------------------------------+ +| 143 | ``LDAPDebug`` | AD/LDAP authentication debug logs | ++--------+-----------------------+--------------------------------------------------------------------------+ +| 144 | ``LDAPTrace`` | AD/LDAP authentication trace logs. Replaces ``LdapSetings.trace`` from | +| | | Mattermost v9.3. | ++--------+-----------------------+--------------------------------------------------------------------------+ + +Configure target-specific settings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Console target configuration options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Console targets can be either ``stdout`` or ``stderr``. + +- The standard output stream, ``stout``, is typically used for command output that prints the results of a command to the user. +- The standard error stream, ``sterr``, is typically used to print any errors that occur when a program is running. + +File target configuration options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +File targets support rotation and compression triggered by size and/or duration. + ++-------------+----------+---------------------------------------------------------------------------------------------------------------------+ +| **Key** | **Type** | **Description** | ++-------------+----------+---------------------------------------------------------------------------------------------------------------------+ +| filename | string | Full path to the output file. | ++-------------+----------+---------------------------------------------------------------------------------------------------------------------+ +| max_size | number | Maximum size, in megabytes (MB), the log file can grow before it gets rotated. Default is ``100`` MB. | ++-------------+----------+---------------------------------------------------------------------------------------------------------------------+ +| max_age | number | Maximum number of days to retain old log files based on the timestamp encoded in the filename. | +| | | Default is ``0`` which disables the removal of old log files. | ++-------------+----------+---------------------------------------------------------------------------------------------------------------------+ +| max_backups | number | Maximum number of old log files to retain. Default is ``0`` which retains all old log files. | +| | | **Note**: Configuring ``max_age`` can result in old log files being deleted regardless of this configuration value. | ++-------------+----------+---------------------------------------------------------------------------------------------------------------------+ +| compress | bool | Compress rotated log files using `gzip `__. Default is ``false``. | ++-------------+----------+---------------------------------------------------------------------------------------------------------------------+ + +Syslog target configuration options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_static/badges/ent-only.rst + :start-after: :nosearch: + +Syslog targets support local and remote syslog servers, with or without TLS transport. Syslog target support requires Mattermost Enterprise. + ++----------+----------+---------------------------------------------------------------------------------------------------------------------------------+ +| **Key** | **Type** | **Description** | ++----------+----------+---------------------------------------------------------------------------------------------------------------------------------+ +| host | string | IP or domain name of the server receiving the log records. | ++----------+----------+---------------------------------------------------------------------------------------------------------------------------------+ +| port | number | Port number for the server receiving the log records. | ++----------+----------+---------------------------------------------------------------------------------------------------------------------------------+ +| tls | bool | Create a TLS connection to the server receiving the log records. Default is ``false``. | ++----------+----------+---------------------------------------------------------------------------------------------------------------------------------+ +| cert | string | Path to a cert file (.pem) to be used when establishing a TLS connection to the server. | ++----------+----------+---------------------------------------------------------------------------------------------------------------------------------+ +| insecure | bool | Mattermost accepts any certificate presented by the server, and any host name in that certificate. Default is ``false``. | +| | | **Note**: Should only be used in testing environments, and shouldn’t be used in production environments. | ++----------+----------+---------------------------------------------------------------------------------------------------------------------------------+ + +TCP target configuration options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_static/badges/ent-only.rst + :start-after: :nosearch: + +The TCP socket targets can be configured with an IP address or domain name, port, and optional TLS certificate. TCP socket target support requires Mattermost Enterprise. + ++----------+----------+---------------------------------------------------------------------------------------------------------------------------------+ +| **Key** | **Type** | **Description** | ++----------+----------+---------------------------------------------------------------------------------------------------------------------------------+ +| host | string | IP or domain name of the server receiving the log records. | ++----------+----------+---------------------------------------------------------------------------------------------------------------------------------+ +| port | number | Port number for the server receiving the log records. | ++----------+----------+---------------------------------------------------------------------------------------------------------------------------------+ +| tls | bool | Create a TLS connection to the server receiving the log records. Default is ``false``. | ++----------+----------+---------------------------------------------------------------------------------------------------------------------------------+ +| cert | string | Path to a cert file (.pem) to be used when establishing a TLS connection to the server. | ++----------+----------+---------------------------------------------------------------------------------------------------------------------------------+ +| insecure | bool | Mattermost accepts any certificate presented by the server, and any host name in that certificate. Default is ``false``. | +| | | **Note**: Should only be used in testing environments, and shouldn’t be used in production environments. | ++----------+----------+---------------------------------------------------------------------------------------------------------------------------------+ +| tag | string | Syslog tag field. | ++----------+----------+---------------------------------------------------------------------------------------------------------------------------------+ + +---- + +Frequently asked questions +-------------------------- + +Does Mattermost have an audit log besides the system ``auditd``? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Yes. See the `audit logging <#audit-logging-beta>`__ documentation for details. + +When syslog is configured as the target, does it contain the IP address of the emitter of the data (i.e., the Mattermost app node)? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Yes. That is a function of the syslog daemon (receiver). Typically, all the log lines are prefixed with a timestamp and the hostname of the node sending the data. For example, a log line starts with: ``Nov 28 10:56:59 tower kernel: [1072437.431123] ....``, where ``tower`` is the hostname of the server that generated the log line. + +Once audit logs are enabled, can audit logging track events where an admin disables or modifies the audit log settings? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Yes, though it depends on how audit logs are configured. Audit log config can be specified via REST API, mmctl, System Console, file on disk, and using environment variables. When changes are made via the REST API or System Console, there is an audit record. However, the Mattermost server can't capture changes to a configuration file or via environment variables. + +Do server logs show any information about a service or similar stopping/updating when auditing would be disabled? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Yes. When updating the audit log configuration via REST API, mmctl, or System Console, the last event of the audit log should be about the admin user updating the config of the server, which helps your security team identify which actions took place in the system and by whom. + +How do I omit incoming webhook details from the logs? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +See `enable-webhook-debugging `__ + +How do I adjust the maximum log field size? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +See `maximum-field-size `__ diff --git a/source/onboard/sso-saml-keycloak.rst b/source/onboard/sso-saml-keycloak.rst index a8bd5df7e71..91b7e6f76cf 100644 --- a/source/onboard/sso-saml-keycloak.rst +++ b/source/onboard/sso-saml-keycloak.rst @@ -14,70 +14,76 @@ Set up a connection app for Mattermost SSO ------------------------------------------- .. note:: - This was tested with Keycloak v18.0.0. + This was tested with Keycloak v22.0.5. Additionally, you don't typically need to make a realm dedicated to Mattermost. We recommend adding Mattermost as a client to your primary realm. 1. Log in to Keycloak as an administrator. -2. Select **Clients**, then **Create** and **Save**. You'll use this client ID in a later step. +2. Select **Clients**, then **Create client**. You'll use this client ID in a later step. + - **Client type**: ``SAML`` - **Client ID**: ``mattermost`` - - **Client Protocol**: ``saml`` -3. Edit the Mattermost client to have the below values: +3. Click **Next** and update the following values: - - **Enabled**: **ON** - - **Encrypt Assertions**: **ON** - - **Force Name ID Format**: **ON** - - **Name ID Format**: **Email** - - **Valid Redirects**: ``https://<>/login/sso/saml`` - - **Base URL**: ``https://<>/login/sso/saml`` + - **Home URL**: ``https://<>/login/sso/saml`` + - **Valid redirect URIs**: ``https://<>/login/sso/saml`` - .. image:: ../../source/images/keycloak_1_client_settings.png - :alt: In Keycloak, create the Mattermost client, specify the Client ID and Client Protocol, then save your changes. +4. **Save** the client. -4. Save the client config. +5. Under the **Settings** tab, update the following values: -5. Navigate to **Keys** within the client config. + - **Enabled**: **On** + - **Name ID format**: ``email`` + - **Force Name ID format**: **On** + - **Sign Documents**: **Off** -6. Select **Generate new keys**. + .. image:: ../../source/images/keycloak_1_client_settings.png + :alt: In Keycloak, create the Mattermost client, specify the Client ID and Client Protocol, then save your changes. -7. Select **Export**, use the values below, and then select **Download**. Once you've downloaded it, navigate back to the Mattermost client in Keycloak for the next steps. +6. Navigate to the **Keys** tab. - - **Archive Format**: ``PKCS12`` - - **Key Alias**: ``mattermost`` - - **Key Password**: ``mattermost`` - - **Store Password**: ``mattermost`` + - **Client signature required**: **Off** + - **Encrypt Assertions**: **On** + + - Click **Generate** + - Download the **private.key** file. + - Click **Confirm** + + - Click **Export** and update the following values: + + - **Archive Format**: ``PKCS12`` + - **Key Alias**: ``mattermost`` + - **Key Password**: ``mattermost`` + - **Store Password**: ``mattermost`` .. note:: - - In the image below, we used `Mattermost` for the `Realm Certificate Alias`. You can use any value that you would like here, as it's designed to identify what this certificate is within your Keycloak realm. + In the image below, we used `Mattermost` for the `Realm Certificate Alias`. You should use your Realm Name here, as it's designed to identify what this certificate is within your Keycloak realm. .. image:: ../../source/images/keycloak_2_saml_keys.png :alt: In Keycloak, on the Keys tab, generate new keys, export using the values documented, then select Download. -8. Add the default attributes: +7. Navigate to the **Client scopes** tab. - a. Within your Mattermost client select **Mappers**. - b. Select **Add Buildin** + a. Select **mattermost-dedicated** + b. Click **Add predefined mapper** c. Select the **X500 email**, **X500 givenName**, and **X500 surname** attributes. - d. Select **Add selected**. + d. Click **Add**. .. image:: ../../source/images/keycloak_3_add_builtins.png :alt: In Keycloak, on the Mappers tab, add default attributes -9. Add the username and ID attribute. +8. Add the username and ID attribute. If you're planning to sync your SAML users with LDAP within Mattermost, the ID value used here must match with your Mattermost LDAP ``ID Attribute``. - a. With the **Mappers** section of your client, select **Create**. + a. Select **Add Mapper** -> **By Configuration** -> User Property. b. Set **Name** to ``Username``. - c. Under Mapper Type select **User Property**. - d. Set **Property** to ``username`` (This is case sensitive and must be lowercase). - e. Set **SAML Attribute Name** to ``username``. - f. Select **Save**. - g. Repeat this step and use the property of ``id`` to create the ID Attribute. + c. Set **Property** to ``username`` (This is case sensitive and must be lowercase). + d. Set **SAML Attribute Name** to ``username``. + e. Select **Save**. + f. Repeat the above steps and use the property of ``id`` to create the ID Attribute. .. image:: ../../source/images/keycloak_4_create_username_attribute.png :alt: In Keycloak, on the Mappers tab, create a protocol mapper, then save your changes. @@ -87,7 +93,7 @@ Set up a connection app for Mattermost SSO :alt: Example of protocol mapper configuration. -10. Get the metadata URL from Keycloak: +9. Get the metadata URL from Keycloak: a. Within your Realm, select **Realm Settings**. b. At the bottom of the **General** tab you should see a **SAML 2.0 Identity Provider Metadata** endpoint. Right-click and copy this URL. Store for the next step. @@ -118,7 +124,7 @@ Configure SAML for Mattermost .. image:: ../../source/images/keycloak_5_mattermost_config.png :alt: In the System Console, configure SAML as documented, where the Service Provider Identifier matches the Client ID you configured in Keycloak. -4. Configure the Encryption using the key you downloaded in step 8 of the Keycloak config. +4. Configure the Encryption using the key you downloaded in step 6 of the Keycloak config. a. Generate the ``.crt`` file from the ``.p12`` file. @@ -143,7 +149,7 @@ Configure SAML for Mattermost 6. Set attributes for the SAML Assertions, which will update user information in Mattermost. - The attributes below are from steps 8 and 9 above. These values must be the **SAML Attribute Name** within Keycloak. See `documentation on SAML configuration settings `__ for more details. + The attributes below are from steps 7 and 8 above. These values must be the **SAML Attribute Name** within Keycloak. See `documentation on SAML configuration settings `__ for more details. - **Email Attribute**: ``email`` - **Username Attribute**: ``username`` diff --git a/source/onboard/system-admin-roles.rst b/source/onboard/system-admin-roles.rst index d66323f26d6..a6d7851bb68 100644 --- a/source/onboard/system-admin-roles.rst +++ b/source/onboard/system-admin-roles.rst @@ -1,7 +1,7 @@ Additional System Admin roles ============================== -.. include:: ../_static/badges/allplans-cloud-selfhosted.rst +.. include:: ../_static/badges/ent-cloud-selfhosted.rst :start-after: :nosearch: *Available in legacy Mattermost Enterprise Edition E20* diff --git a/source/templates/index.html b/source/templates/index.html index 03671eeade9..3e7a4a9dd47 100644 --- a/source/templates/index.html +++ b/source/templates/index.html @@ -483,7 +483,7 @@

Get help

- © Mattermost, Inc. 2023. Terms + © Mattermost, Inc. 2024. Terms of Use | Privacy Policy | Cookie Policy