docs/main/administration-guide/comply/legal-hold.mdx
A Legal Hold, also known as a litigation hold, is a process that an organization uses to preserve all forms of relevant information when litigation is reasonably anticipated. It's a requirement established by the Federal Rules of Civil Procedure (FRCP) in the United States and similar laws in other jurisdictions.
Primary use cases include:
Mattermost is used as a secure collaboration hub by technical and operational teams, with critical documents and data shared on a daily basis. Thus, Legal Hold is a key requirement for Enterprises and public sector organizations who have deployed Mattermost for their teams, to meet compliance & auditory requirements while minimizing risk.
Mattermost Legal Hold can be combined with eDiscovery integration and data retention policies to customize the data retained and deleted to comply with compliance requirements.
Check out this YouTube sneak peek demo to learn about Mattermost's Legal Hold workflow.
<iframe width="560" height="315" src="https://www.youtube.com/embed/86c8NoOxlQw" alt="Mattermost Legal Hold workflow" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>Below are step-by-step instructions on how to carry out a Legal Hold for Mattermost using the Mattermost Legal Hold plugin.
Legal Hold is available in Mattermost Enterprise. Learn more about the Enterprise plan & request a quote online at https://mattermost.com/pricing/
Establish a policy for when to implement a Legal Hold. This should be developed in consultation with your legal counsel and should include procedures for identifying relevant users (those who have potentially relevant information).
Establishing a Legal Hold policy first enables you to configure the Mattermost system correctly to meet your compliance & auditory requirements, minimizing associated risk.
When the Legal Hold integration is enabled, you can configure when it runs using the format HH:MM ±HHMM and +0000 for UTC.
You can configure a custom Amazon S3 bucket for Legal Holds by specifying Amazon S3 configuration settings. If no S3 configuration is specified, the Mattermost server file store used. Learn more about file storage configuration options in our product documentation.
You can optionally configure a data retention policy to control how long data and file attachments are retained in the Mattermost database.
In Mattermost, create a Legal Hold by completing the following steps:
While a Legal Hold is in place, you can edit details of the Legal Hold, access the Legal Hold Secret, as well as download a copy of the preserved data to your local machine.
Select the Edit icon to change the name of the Legal Hold, add or remove users, change the end date, as well as include or exclude public channels.
A Legal Hold secret enables you to verify the authenticity of the data for a Legal Hold in Mattermost.
Select the Show icon to display the Legal Hold secret key. Keep a copy of this key in a secure location.
To verfiy the contents of the files in this Legal Hold, you must append the processor command with the following flag: --legal-hold-secret <KEY>. The output verifies the file and returns the authenticity state of files along with the rest of the output for the processor, as follows:
Success:
Secret key was provided, verifying legal holds...
- Verifying Legal Hold *processor9*: Verified
Error:
...
Secret key was provided, verifying legal holds...
- Verifying Legal Hold *processor9*: [Error] hash mismatch for file: legal_hold/processor9_i7k1dbkipiyojeess6ozi4agyr/index.json
...
Select the Download icon to download a copy of the preserved data to a location on your local machine. Note, no data will be available to download until at least one scheduled job is completed. This may take up to 24 hours.
Once the Legal Hold has completed, release it to take users off of the Legal Hold by selecting the Release option to the right of the Legal Hold task.
Once a Legal Hold is released, all data is irretrievably deleted from Mattermost and can't be recovered.
Only Mattermost system admins can implement a Legal Hold.
No, users won't be notified if they're placed under a Legal Hold, and no reference to Legal Holds will be visible in their Mattermost client or accessible via the Mattermost API. This allows for investigations to be conducted without influencing user behavior and without conflicts of interest.
The Legal Hold covers all messages and file uploads shared in conversations where the Legal Hold is active, including messages posted by plugins, bots or webhooks. This includes messages or files shared in public channels, private channels, direct messages and group messages.
However, Legal Hold does not apply to reactions, collaborative playbooks, or audio calls.
Yes, users can delete messages, but they are retained for the purposes of Legal Hold when implemented with the aforementioned steps.
Yes, but this is only guaranteed for existing and future messages/files once Legal Hold is activated. It won't recover messages or files that were deleted before the Legal Hold was activated.
No. While they serve a related use case, they are not the same.
Legal Hold is an initial step to ensure relevant electronically stored information (ESI) is preserved. On the other hand, e-discovery is a multi-step process that uses this preserved data to identify, collect, preserve, process, review, and produce ESI in the context of a legal or investigative process.
Learn more about extracting data for e-discovery in our product documentation.
If you plan to use an existing S3 bucket for Legal Hold data storage, and your existing S3 bucket has versioning enabled, we strongly recommend using a dedicated S3 bucket with versioning disabled.
The Legal Hold plugin frequently modifies files in the legalhold directory, and when S3 bucket versioning is enabled, each modification creates a new version. This can result in a rapid accumulation of object versions, increased storage costs, potential performance impact, higher S3 API usage, and complicating version management over time. See the S3 Lifecycle Rules documentation for additional details.
To make use of the Legal Hold data, you use the processor tool available on the Mattermost GitHub repository. This will output a self-contained HTML site you can open with your browser.
Download and setup the processor tool:
$ chmod +x processor-vX.X.X-<platform> # Replace with the actual filename you downloaded
Usage:
$ ./processor --legal-hold-data ./legalholddata.zip --output-path ./path/to/where/you/want/the/html/output --legal-hold-secret "your secret"
Arguments:
--legal-hold-data: Path to the Legal Hold zip file downloaded from Mattermost--output-path: Directory where the HTML output will be generated--legal-hold-secret: (Optional) Used as a security measure for an operator to ensure the authenticity of a downloaded zip file. The operator can copy the key corresponding to a particular "hold" from the Legal Hold Plugin settings page in the System Console by selecting the Show icon next to the Legal Hold entry.Yes. Filtering isn't done based on archive or deleted status. However, archived channels can be permanently deleted based on Data Retention settings, at which point they will no longer appear in legal hold reports.
Yes. Channels are included when a target user was a member at any time during the legal hold start and end dates.
Yes. Filtering isn't done based on user deactivation state.
Yes. Data is collected from group messages like any public or private channel or direct message.