Opening a Support Ticket for Self-Managed Deployments

Sven Hüster
Updated

When opening a support ticket, providing comprehensive information upfront helps us resolve your issue faster. We use the C.L.U.E.S. framework to gather what we need:

  • Configuration
  • Logs
  • Users affected
  • Environment
  • Steps to reproduce

With these details, we can quickly identify the root cause—whether it's a configuration issue or a product bug—and get you back on track.

Getting Support

Enterprise customers can open tickets through the Enterprise Support Portal.

Community support is available to all users via:

Quick Start: Generate a Support Packet

Recommended: The fastest way to provide diagnostic information is to generate a Support Packet. Available for Professional and Enterprise customers, the Support Packet automatically collects most of the information described in this guide.

What's included in a Support Packet

A Support Packet is a ZIP file containing:

  • Mattermost configuration (sanitized - passwords and sensitive data removed)
  • Server logs from all cluster nodes
  • Plugin configurations and diagnostics
  • System metadata (version, server ID, license info)
  • Performance metrics (if Metrics plugin installed)
  • Database connection info
  • LDAP diagnostics (including vendor info)
  • Job server details
  • Calls plugin diagnostics (version, session stats)
Important: Confidential data like passwords and tokens are automatically stripped, but you should still review the packet before sharing and sanitize any remaining sensitive information.

How to generate a Support Packet

Before generating:

  1. Enable debug logging: System Console > Environment > Logging
    • Set Output logs to file to true
    • Set File Log Level to DEBUG
  2. Reproduce the issue (if possible) so relevant errors are captured

Option 1: System Console (GUI)

  1. Go to System Console
  2. Open the menu (☰) and select Commercial Support
  3. Click Download Support Packet
  4. A ZIP file downloads to your local machine
  5. Check for any warnings in the included warning.txt file

Option 2: mmctl (Command Line)

mmctl system supportpacket

The packet will be generated and saved locally. You can specify additional options:

# Generate with performance metrics
mmctl system supportpacket --performance-metrics

# Save to specific location
mmctl system supportpacket --output /path/to/save/

After generating

  1. Review the packet contents for any sensitive information specific to your organization
  2. Attach the ZIP file to your support ticket
  3. Disable debug logging after collection to prevent log bloat and performance impact

When you can't use Support Packet

If you're on Team Edition or can't generate a Support Packet for any reason, manually collect the information detailed in the sections below.

General Guidelines

When providing diagnostic information:

  • Completeness matters - Share entire log files and complete configurations rather than snippets. Context is crucial for diagnosis.
  • Use plaintext when possible - Text files are searchable and easier to analyze than screenshots. Screenshots are great for showing UI issues, but use text for logs and configs.
  • Sanitize sensitive data - Remove credentials, API keys, passwords, and personal information. When redacting, preserve special characters (they often cause configuration issues).
  • Show, don't just tell - Include screenshots or screen recordings of unexpected behavior so we see exactly what your users experience.
  • Be timely - Provide information as soon as possible after an issue occurs. Fresh logs are more useful than old ones.

Configuration

Why we need it

Configuration settings control how Mattermost behaves and integrates with your infrastructure. Many issues stem from misconfigured settings. A complete picture of your setup helps us identify problems and reproduce bugs.

Note: If you've generated a Support Packet, your configuration is already included (sanitized). The information below is for manual collection or understanding what the packet contains.

What to include

Mattermost configuration:

  • Your config.json file or database configuration export
  • Relevant environment variables
  • Plugin configurations (if applicable)

Infrastructure configuration:

  • Reverse proxy config (NGINX, HAProxy, Apache, cloud load balancer)
  • TLS/SSL certificate setup
  • Database configuration

Authentication systems:

  • SAML IdP configuration (screenshots from provider UI are fine)
  • LDAP/AD settings (confirmed by your directory admin)
  • OAuth provider settings

Integrations:

  • Configurations for systems Mattermost connects to (Jira, GitLab, etc.)
  • Webhook configurations
  • Bot/integration service settings

How to access configuration

Mattermost config

If stored as a file (default):

cat /opt/mattermost/config/config.json

If stored in database:

mmctl config get

Or via SQL:

SELECT Value FROM Configurations WHERE Active = 1;

NGINX configuration

  • Main config: /etc/nginx/nginx.conf
  • Virtual server config: /etc/nginx/sites-available/mattermost (Ubuntu/Debian)

Provide both files if possible.

SAML configuration

Take screenshots of your Mattermost service configuration in your SAML provider (similar to our setup documentation).

LDAP configuration

Have your LDAP admin confirm these settings:

  • Server hostname and port
  • Connection security (TLS/STARTTLS)
  • Bind DN and credentials
  • Base DN for searches
  • User, Guest, Group, and Admin filters
  • Attribute mappings

Cloud/container configurations

If running on AWS, Azure, GCP, or in containers (Docker/Kubernetes), include:

  • Infrastructure-as-code configs (Terraform, CloudFormation)
  • Container orchestration configs
  • Helm chart values
  • Environment variables

Logs

Why we need them

Logs capture what's happening under the hood. Error messages, warnings, and debug traces help us pinpoint exactly where and why things go wrong.

Note: If you've generated a Support Packet, logs from all cluster nodes are already included. The information below is for manual collection or when you need additional specific logs.

Available logs

Mattermost server logs

  • /opt/mattermost/logs/mattermost.log - General application log
  • /opt/mattermost/logs/notifications.log - Push notification log

System logs

  • Use journalctl on systemd-based systems
  • Check /var/log/ for traditional syslog entries

Proxy logs

  • NGINX: /var/log/nginx/access.log and error.log
  • Apache: /var/log/apache2/ or /var/log/httpd/
  • Cloud load balancer logs (check your cloud provider console)

Database logs

  • MySQL: Often in /var/log/mysql/
  • PostgreSQL: Check pg_log directory or journalctl -u postgresql

External system logs

  • SAML provider logs
  • LDAP/AD server logs
  • Integration service logs (Jira, GitLab, etc.)

How to collect logs

Enable debug logging first

Go to System Console > Environment > Logging and set:

  • Console log level: DEBUG
  • File log level: DEBUG

For trace logging

(Elasticsearch, SAML, LDAP, database issues), edit config.json:

{
  "SqlSettings": {
    "Trace": true
  },
  "LdapSettings": {
    "Trace": true
  }
}

 

Warning: Trace logs are verbose and may contain sensitive data. Only enable when necessary and sanitize before sharing.

Collect Mattermost logs

If you know when the issue started:

sudo journalctl -u mattermost --since "2025-11-14 10:30:00" > mattermost.log

Or grab the log files directly:

sudo tar -czf mattermost-logs.tgz /opt/mattermost/logs/

Collect system-wide logs

sudo journalctl --since "2025-11-14 10:30:00" --until "2025-11-14 11:00:00" > system.log

Handle large log files

Compress logs:

tar -czf /tmp/mattermost-logs.tgz /opt/mattermost/logs/

Split into smaller chunks if needed:

mkdir -p /tmp/mattermost-logs-split
cd /tmp/mattermost-logs-split
tar czf - /opt/mattermost/logs/ | split -b 20m - logs.tgz.

This creates logs.tgz.aa, logs.tgz.ab, etc.

Users Affected

Why we need it

Identifying patterns in which users experience issues helps isolate the problem. Is it all users, specific teams, certain authentication types, or particular clients?

What to include

User characteristics:

  • Usernames or user IDs (sanitize if needed)
  • Authentication method (email/password, SAML, LDAP, etc.)
  • Teams and channels they're in
  • Any groups or roles assigned
  • Account creation date (especially for "new user" issues)

Client information:

  • Desktop app version and OS
  • Mobile app version and device type
  • Browser version (for webapp issues)
  • Connection method (VPN, corporate network, remote, etc.)

Problem scope:

  • Total users affected
  • Percentage of user base impacted
  • Geographic distribution (if relevant)
  • Whether it affects specific groups (admins, guests, system roles)

Common factors:

  • Recent changes (password resets, role changes, team joins)
  • LDAP/AD sync status
  • Shared integrations or plugins used

For support agents (internal):

  • Customer name and contacts
  • License type (Professional, Enterprise)
  • Support tier
  • Account manager

Environment

Why we need it

Your infrastructure significantly impacts Mattermost performance and behavior. Network configuration, server specs, and integration points all matter.

Note: If you've generated a Support Packet, basic environment information (version, license, server ID) is included in the metadata.yaml file. You may still need to provide additional infrastructure details as outlined below.

What to include

Mattermost deployment:

  • Mattermost version (e.g., v9.2.4)
  • Edition (Team, Professional, Enterprise)
  • Deployment method (binary, Docker, Kubernetes, cloud marketplace)
  • High availability setup (if clustered)
  • Number of active users

Server infrastructure:

  • OS and version (e.g., Ubuntu 22.04, RHEL 9, Amazon Linux 2023)
  • Server specs (CPU, RAM, disk type)
  • Virtualization platform (VMware, Hyper-V, KVM, cloud VM)
  • Container runtime (Docker, containerd, Podman)
  • Orchestration (Kubernetes version, Helm chart version)

Network components:

  • Reverse proxy and version (e.g., NGINX 1.24, Apache 2.4)
  • Load balancer type (AWS ALB, HAProxy, F5)
  • CDN usage (Cloudflare, CloudFront, etc.)
  • Firewall/WAF rules
  • VPN or private network setup

Database:

  • Type and version (e.g., PostgreSQL 15.2, MySQL 8.0)
  • Hosting (self-hosted, RDS, Cloud SQL)
  • Read replicas or clustering
  • Connection pooling (PgBouncer, ProxySQL)

Authentication:

  • SAML provider and version (Okta, Azure AD, OneLogin, Keycloak)
  • LDAP/AD version (Active Directory 2019, OpenLDAP 2.6)
  • Multi-factor authentication provider

File storage:

  • Local filesystem or S3-compatible object storage
  • Storage backend (AWS S3, MinIO, Azure Blob)
  • CDN for file delivery

Monitoring & observables:

  • Monitoring tools in use (Prometheus, Grafana, Datadog)
  • Log aggregation (ELK stack, Splunk, CloudWatch)

Example environment descriptions

Simple deployment:

Mattermost v9.2.4 Professional
Ubuntu 22.04 LTS (2 vCPU, 4GB RAM)
NGINX 1.24.0
PostgreSQL 15.2 (RDS)
~100 active users

High availability deployment:

Mattermost v9.2.4 Enterprise (clustered)
- App servers: 4x Ubuntu 22.04 (4 vCPU, 8GB RAM each)
- AWS Application Load Balancer
- PostgreSQL 15.2 (RDS Multi-AZ) with read replica
- Amazon S3 for file storage
- CloudFront CDN
- Elasticsearch 8.11 (3 nodes)
- Azure AD SAML authentication
- ~5,000 active users

Steps to Reproduce

What it is

A clear, step-by-step description of actions that lead to the unexpected behavior. This helps us recreate the issue in our environment and verify fixes.

How to provide reproduction steps

Be specific and sequential:

  1. Start with initial conditions (fresh login, specific channel, etc.)
  2. List each action in order
  3. Include what you click, type, or configure
  4. Note the expected result
  5. Describe the actual (incorrect) result

Example:

1. Log in as a regular user (not admin)
2. Navigate to Town Square channel
3. Type `/todo add Test task` and press Enter
4. Click the "View" button that appears
5. Expected: Todo modal opens showing the task
6. Actual: Nothing happens, browser console shows 403 error

Include media evidence:

Screenshots and screen recordings are incredibly valuable. They show us exactly what you're seeing.

Capturing screenshots and recordings

macOS:

  • Screenshot: Cmd + Shift + 4, select area
  • Screen recording: Cmd + Shift + 5, select recording options

Windows:

  • Screenshot: Win + Shift + S (Snipping Tool)
  • Screen recording: Win + G (Xbox Game Bar) or use OBS Studio

Linux:

  • Screenshot: PrtScn or use Flameshot, Spectacle
  • Screen recording: Use SimpleScreenRecorder or OBS Studio

iOS:

  • Screenshot: Volume Up + Power button
  • Screen recording: Control Center > Screen Recording
  • Full iOS instructions

Android:

  • Screenshot: Volume Down + Power button (varies by device)
  • Screen recording: Quick Settings > Screen Record
  • Full Android instructions

Browser Developer Tools:

For web app issues, include browser console output:

  1. Press F12 to open Developer Tools
  2. Go to Console tab
  3. Reproduce the issue
  4. Right-click in console > Save as... or take a screenshot

Quick Checklist

Before submitting your support request, ensure you have:

  • ☐ Support Packet generated (Professional/Enterprise customers - recommended!)
  • Or manual collection of the items below:
  • ☐ Complete configuration files (sanitized)
  • ☐ Relevant logs with debug level enabled
  • ☐ List of affected users and common characteristics
  • ☐ Detailed environment description
  • ☐ Clear reproduction steps
  • ☐ Screenshots or recordings of the issue
  • ☐ Any error messages from browser console or logs
  • ☐ Timeline of when the issue started
Remember: The Support Packet automatically includes most configuration, logs, and environment data. Generate one first if you're a Professional or Enterprise customer!

Additional Resources

For more information, see:

Related to

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.