Best Practices for Managing Attachments in Atlassian Confluence

[#1]

p.s: This post is a version improved by Atlassian Intelligence 🪄.
The link to the original version is available at the end of the post.

Introduction

Attachments play a vital role in Atlassian Confluence, yet many administrators often overlook them until significant problems arise.

This guide is rooted in our extensive experience with various clients and aims to share best practices that can assist fellow Confluence administrators.

We'll break down the discussion into 5 key considerations for effective Confluence Administration:

• Integrity

• Security

• Performance

• Cost

• Uptime

In each section, we’ll delve into how attachments impact these areas and suggest solutions to tackle potential challenges.

Integrity

Have you ever tried to download an attachment only to be met with the dreaded Attachment File Not Found error?

A system is ineffective if users can’t retrieve the information it holds. Without trust, users are unlikely to store their work in the system.

Attachments can go missing in Confluence for several reasons:

• Deleted by antivirus software in the background

• Upload errors or blocks by Web Application Firewalls (WAF)

• File uploads when Confluence lacks sufficient disk space

• Human errors during backup or restore processes during server migrations

• Ransomware attacks

Another issue can arise when newer versions of attachments are accidentally overwritten due to multiple users editing them simultaneously. The Cenote Lockpoint app for Confluence resolves this by allowing attachments to be checked out for exclusive editing.

In rare cases, attachments may lack metadata (like creation date and author), which can be problematic when importing data into Confluence Cloud. The Attachment Checker helps verify metadata during uploads and identifies affected files in the Missing Attachments Scanner report.

Security

A common security vulnerability for web applications is CWE-434 (Unrestricted Upload of File with Dangerous Type).

A malicious file can compromise security in two main ways:

1. The file is processed on the Confluence server, leading to unwanted code execution.

2. The file is downloaded by users, potentially resulting in virus infections.

To mitigate these risks, we recommend implementing a list of safe file extensions that can be attached to Confluence.

For sites with public users, MIME type checks add an extra layer of security against malicious users who might rename file extensions to bypass checks.

Another security concern is unintentional information disclosure or wiki leaks. Sometimes, an intern or external vendor may download all attachments for non-work-related purposes.

While securing Confluence spaces with appropriate permissions is the simplest solution, it’s also possible to manage these groups by:

• Restricting their ability to download files from Confluence

• Keeping a log of download activities within the space

Performance

One of my favorite features in Confluence is the ability to preview documents directly without needing to download them. However, the document conversion process for very large files can lead to performance issues.

When you insert a file into a page (like a Word document or Excel spreadsheet), Confluence converts the contents to a viewable format for inline display, previews, or macros. This can be quite memory and CPU-intensive, sometimes causing out-of-memory errors with complex files.

We had a customer who faced unresponsive Confluence due to users uploading specific file types. To help admins quickly identify if this was a contributing factor when users reported slowdowns, we developed the Large Attachment Tracker.

If your Confluence instance serves as a corporate intranet or learning management system, it may slow down after major events when many users access videos and photos simultaneously.
Since Confluence isn't a video streaming server, it may struggle to handle high workloads when numerous users download large files at once.

It’s best to distribute photos and videos across several pages and disable autoplay to avoid excessive resource consumption.

Another common cause of slowdowns is virus scanners. Increased CPU and disk I/O can occur as files are inspected. Atlassian has published a Knowledge Base article outlining best practices and workarounds for performance issues.

A potential solution is to check each file only once upon upload, reducing unnecessary checks during subsequent access. This can be done by integrating with a compatible virus scanner and queuing uploaded attachments for scanning without overloading server resources.

Cost

For large Confluence sites, managing costs can be an ongoing challenge. Users upload attachments daily, but disk space is limited. If no action is taken, disk space will eventually fill up.

Many assume that increasing disk storage is a minor issue, given its affordability today.

However, the reality is that true costs extend beyond just purchasing a larger hard disk. Several cost types are affected:

Type of Cost	How it affects
Storage cost	Upgrading to a larger hard disk is necessary. For those migrating to Confluence Cloud, an upgrade from the Standard to the Premium plan is required once disk usage exceeds 250GB.
Backup cost	Disk space usage increases since it’s common to maintain multiple generations of backups.
Operational cost	This often-overlooked cost includes energy consumption and the time system engineers spend on increasing disk storage, managing backups, performing upgrades, reindexing, executing virus scans, migrating to new hardware, and generating reports on disk usage by Confluence spaces.
User cost	Larger files take more time to download and open. Each user may spend an extra 5 seconds per download. A typical user downloads five such files daily. In a company with 500 users, this can accumulate to a savings of 3.4 hours per day or 104 hours per month. When disk space is insufficient, users need to spend time on housekeeping tasks.
Bandwidth cost	This may not apply to everyone. We have a customer whose users work on ships with limited and expensive Internet bandwidth. They prefer all images to be scaled down instead of retaining high-resolution quality.

There are two approaches to tackle the challenge of ever-growing attachments.

The first approach is to remove content that is no longer needed. Two apps on the Atlassian Marketplace allow users to identify unused attachments and facilitate bulk deletion:

• Delete Attachments (Statistics)

• Delete Unused Attachments

Admins can also implement retention rules to delete historical versions of attachments. However, this carries risks, as some old versions may contain important data.

Another approach is to prevent excessive disk usage growth by limiting the uploads of very large and unnecessary files.

The Attachment Checker provides admins with a summary to identify which teams are consuming significant disk space.

With this information, admins can pinpoint misuse and invalid file types that should be blocked.

It’s also possible to enforce quotas to warn or prevent users from additional uploads until housekeeping is completed.

Additionally, space admins and users can monitor their space usage to facilitate housekeeping efforts.

For those interested, we offer another guide on How to free up disk space on Confluence for further information.

Uptime

Finally, as the total size of attachments increases, the time required for backups and upgrades also lengthens, resulting in extended downtime during scheduled maintenance.

Conclusion

While this article is particularly relevant for larger or enterprise-scale Confluence instances, it’s wise to address these issues early rather than investing more effort in cleanup later.

Source: Best Practices in Confluence Administration – Attachments