From 5d4c07114a93c8afc589d1cb70af99e718e50fad Mon Sep 17 00:00:00 2001 From: "Carrie Warner (Mattermost)" <74422101+cwarnermm@users.noreply.github.com> Date: Thu, 21 Dec 2023 09:40:40 -0500 Subject: [PATCH 1/2] Overhauled logging > replace audit-logging docs (#6813) * Overhauled logging > replace audit-logging docs * Update source/manage/logging.rst Co-authored-by: Colton Shaw <46071821+coltoneshaw@users.noreply.github.com> * Update source/manage/logging.rst Co-authored-by: Colton Shaw <46071821+coltoneshaw@users.noreply.github.com> * Update source/manage/logging.rst Co-authored-by: Colton Shaw <46071821+coltoneshaw@users.noreply.github.com> * Incorporated reviewer feedback * Fixed broken table syntax * Update source/manage/logging.rst Co-authored-by: Doug Lauder * Update source/manage/logging.rst Co-authored-by: Doug Lauder * Update source/manage/logging.rst * Update source/manage/logging.rst * Update source/manage/logging.rst * Reworked FAQ, renamed audit page * Updated log file path --------- Co-authored-by: Colton Shaw <46071821+coltoneshaw@users.noreply.github.com> Co-authored-by: Doug Lauder Co-authored-by: Stu Doherty --- source/about/editions-and-offerings.rst | 2 +- source/{comply => archive}/audit-log.rst | 0 .../comply/embedded-json-audit-log-schema.rst | 8 +- source/conf.py | 16 + .../experimental-configuration-settings.rst | 395 +++++--------- .../logging-configuration-settings.rst | 154 +++--- source/guides/self-hosted-administration.rst | 4 +- source/manage/logging.rst | 489 ++++++++++++++++++ 8 files changed, 717 insertions(+), 351 deletions(-) rename source/{comply => archive}/audit-log.rst (100%) create mode 100644 source/manage/logging.rst 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/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..ca9de7f88dc 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": diff --git a/source/configure/experimental-configuration-settings.rst b/source/configure/experimental-configuration-settings.rst index d38940fe25b..3f9379c1c5f 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>`__ +- `Experimental/Beta Audit logging configuration settings <#experimental-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 ---- +Experimental/Beta audit logging configuration options +----------------------------------------------------- + +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 (Experimental 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 (Experimental 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 (Experimental 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 (Experimental 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 (Experimental 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 (Experimental 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 (Experimental 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 -------------------------------------------------------------------- @@ -945,273 +1071,6 @@ Used to control the buffer of outstanding Push Notification messages to be sent. :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/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/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/manage/logging.rst b/source/manage/logging.rst new file mode 100644 index 00000000000..37fab65eb24 --- /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-experimental-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 `__ \ No newline at end of file From 562f559a542af0e7e7707e817af3f7a41f18c53b Mon Sep 17 00:00:00 2001 From: "Carrie Warner (Mattermost)" <74422101+cwarnermm@users.noreply.github.com> Date: Thu, 21 Dec 2023 10:22:30 -0500 Subject: [PATCH 2/2] Updated audit log experimental tags to beta (#6859) --- .../experimental-configuration-settings.rst | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/source/configure/experimental-configuration-settings.rst b/source/configure/experimental-configuration-settings.rst index 3f9379c1c5f..4b470998ceb 100644 --- a/source/configure/experimental-configuration-settings.rst +++ b/source/configure/experimental-configuration-settings.rst @@ -5,7 +5,7 @@ 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/Beta Audit logging configuration settings <#experimental-beta-audit-logging-configuration-options>`__ +- `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>`__ @@ -744,8 +744,8 @@ Enable Bleve for autocomplete queries ---- -Experimental/Beta audit logging configuration options ------------------------------------------------------ +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. @@ -755,7 +755,7 @@ When audit logging is enabled, you can specify size, backup interval, compressio These settings aren't available in the System Console and can only be set in ``config.json``. .. config:setting:: exp-wroteauditfileslocally - :displayname: File name (Experimental Audit Logging) + :displayname: File name (Beta Audit Logging) :systemconsole: N/A :configjson: FileName :environment: N/A @@ -773,7 +773,7 @@ Write audit files locally +--------------------------------------------------------------------------------------------------------------------------------------+ .. config:setting:: exp-auditfilename - :displayname: File name (Experimental Audit Logging) + :displayname: File name (Beta Audit Logging) :systemconsole: N/A :configjson: FileName :environment: N/A @@ -789,7 +789,7 @@ Specify the path to the audit file. +-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. config:setting:: exp-filemaxsize - :displayname: File max size MB (Experimental Audit Logging) + :displayname: File max size MB (Beta Audit Logging) :systemconsole: N/A :configjson: FileMaxSizeMB :environment: N/A @@ -805,7 +805,7 @@ This is the maximum size (in megabytes) that the file can grow before triggering +---------------------------------------------------------------------------------------------------------------------+ .. config:setting:: exp-filemaxage - :displayname: File max age days (Experimental Audit Logging) + :displayname: File max age days (Beta Audit Logging) :systemconsole: N/A :configjson: FileMaxAgeDays :environment: N/A @@ -821,7 +821,7 @@ This is the maximum age in days a file can reach before triggering rotation. The +--------------------------------------------------------------------------------------------------------------------+ .. config:setting:: exp-filemaxbackups - :displayname: File max backups (Experimental Audit Logging) + :displayname: File max backups (Beta Audit Logging) :systemconsole: N/A :configjson: FileMaxBackups :environment: N/A @@ -837,7 +837,7 @@ This is the maximum number of rotated files kept; the oldest is deleted first. T +--------------------------------------------------------------------------------------------------------------------+ .. config:setting:: exp-filecompress - :displayname: File compress (Experimental Audit Logging) + :displayname: File compress (Beta Audit Logging) :systemconsole: N/A :configjson: FileCompress :environment: N/A @@ -853,7 +853,7 @@ When ``true``, rotated files are compressed using ``gzip``. +-------------------------------------------------------------------------------------------------------------------------------------+ .. config:setting:: exp-filemaxqueuesize - :displayname: File max queue size (Experimental Audit Logging) + :displayname: File max queue size (Beta Audit Logging) :systemconsole: N/A :configjson: FileMaxQueueSize :environment: N/A @@ -1065,7 +1065,7 @@ 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