Use the System Console or the mmctl system supportpacket command to generate a Mattermost Support Packet that includes configuration information, logs, plugin details, and data on external dependencies. Confidential data, such as passwords, are automatically stripped.

Contents of a support packet#

A Mattermost Support Packet can contain the following files:

  • metadata.yaml

  • mattermost.log

  • plugins.json

  • sanitized_config.json

  • support_packet.yaml

  • Go performance metrics, including: cpu.prof, heap.prof, and goroutines

  • warning.txt (present when issues are encountered during packet generation)

Note

  • LDAP groups are not included during Support Packet generation. Only LDAP Version and LDAP Vendor are included when present. These values are included in the support_packet.yaml file.

  • From Mattermost v9.11, LDAP Vendor errors are included in the Support Packet. If fetching the LDAP Vendor name fails, the Support Packet generation includes the error in warning.txt. If no LDAP Vendor name is found, the Support Packet lists them as unknown.

Generate the support packet#

Important

Before generating a support packet, go to System Console > Environment > Logging and ensure Output logs to file is set to true, and set File Log Level to DEBUG.

  1. Go to the System Console, and select Commercial Support from the System Console menu.

    Example of available System Console menu options.

  2. Select Download Support Packet. A zip file is downloaded to the local machine. You’ll be notified if any packet files are unavailable during packet generation. See the warning.txt file for details.

Run the mmctl system supportpacket command to generate and download a Support Packet to share with Mattermost Support.

go run ./cmd/mmctl system supportpacket

Downloading Support Packet
Downloaded Support Packet to mattermost_support_packet_.zip

Santitize confidential data#

When present, the following information is santized during packet generation: LdapSettings.BindPassword, FileSettings.PublicLinkSalt, FileSettings.AmazonS3SecretAccessKey, EmailSettings.SMTPPassword, GitLabSettings.Secret, GoogleSettings.Secret, Office365Settings.Secret, OpenIdSettings.Secret, SqlSettings.DataSource, SqlSettings.AtRestEncryptKey, ElasticsearchSettings.Password, All SqlSettings.DataSourceReplicas, All SqlSettings.DataSourceSearchReplicas, MessageExportSettings.GlobalRelaySettings.SmtpPassword, and ServiceSettings.SplitKey. Plugins are not sanitized during packet generation.

Ensure you sanitize any additional confidential details in the plugin.json file before sharing it with Mattermost. Replace details with example strings that contain the same special characters if possible, as special characters are common causes of configuration errors.

Share the packet with Mattermost#

Add the generated support packet to a Mattermost Support ticket, or share with with the Mattermost team you’re working with.

Important

Disable debug logging once you’ve generated the Support Packet. Debug logging can cause log files to expand substantially, and may adversely impact server performance. We recommend enabling it temporarily, or in development environments, but not production enviornments.

Metadata#

From Mattermost v9.11, generated Support Packets include a metadata.yaml file that contains the following information.

Field name

Required/Optional

Description

Example

version

Required

Version of the schema that the current metadata file is compatible with. Current version is 1.

1

type

Required

The type of the packet. Each type of support packet can be mapped to a specific component generating the support packet.

mattermost

generated_at

Required

The date and time the packet was created. Value is in epoch (ms).

1707473288731

server_version

Required

Version of the server that the support packet was generated at. Semver is expected.

9.1.1

server_id

Required

Unique identifier of the server. Expected to be 26 characters or longer.

9qpiszyjr3g8bxda35abcd1234

license_id

Optional

Unique identifier of the current server’s license. Expected to be 26 characters or longer. This field is empty when there’s no license.

abcdejisd67yigqhmkz4ho1234

customer_id

Optional

The id of the customer, as defined in the license file. Expected to be 26 characters or longer. Empty when there’s no license.

a1b2c3d4qbbr5cpkbpbmef123h

extras

Optional

Key/value of any additional information, specific to the plugin/component that generated the file. Can be useful for identifying the contents of the data. Consider adding plugin (or component) versions in order to set expectation regarding the contents of this object.

extras.plugin_id

Required for plugins

The ID of the plugin.

extras.plugin_version

Required for plugins

The version of the plugin.

For example:

version: 1
type: support-packet
generated_at: 1622569200
server_version: 9.1.1
server_id: 8fqk9rti13fmpxdd5934a3xsxh
license_id: 3g3pqn8in3brzjkozcn1kdidgr
customer_id: 74cmws7gf3ykpj31car7zahsny
extras:
 plugin_version: 0.1.0

Go performance metrics#

The Support Packet contains 3 go runtime profiling files:

  • cpu.prof contains a 5-second CPU profile

  • heap.prof contains a heap profile

  • goroutines contains a dump of all the running go routines

These files can be read using pprof.

Use go tool pprof -web X to open a visualization of the profile in your browser, replacing X with the profile’s file name.