Documentation for Confluence 5.4.
Documentation for Confluence OnDemand and earlier versions of Confluence is available too.

Skip to end of metadata
Go to start of metadata

Confluence allows you to store attachments in one of three places:

  • Filesystem - locally in the Confluence home directory
  • Database - in Confluence's configured database
  • WebDAV - remotely on a WebDAV server (*deprecated*)

A System Administrator can configure Confluence's attachment storage via the 'Attachment Storage' option on the 'Administration Console'.

(info) You need to have System Administrator permissions in order to perform this function.

 

On this page:

Related pages:

(warning) The information on this page does not apply to Confluence OnDemand.

Attachment Storage Options

Local File System

By default, Confluence stores attachments in the attachments directory within the configured Confluence home folder. If you are looking to run Confluence Clustered, attachments must be stored in the database.

Database

Confluence gives administrators the option to store attachments in the database that Confluence is configured to use.

Here are some reasons why, as an administrator, you may want to choose this storage system:

  • Ease of backup.
  • Avoiding issues with certain characters in attachment file names.

    Icon

    While storing attachments in the database can offer some advantages, please be aware that the amount of space used by the database will increase because of the greater storage requirements.

WebDAV

Confluence also allows administrators to set an external WebDAV repository as the location for attachment storage.

WebDAV attachment manager deprecated

Icon

The option to store Confluence attachments on a WebDAV server has never worked in a useful fashion, and has not been maintained for many versions.

  • The WebDAV attachment manager will be deprecated from Confluence 2.7, and will be removed from a later version of Confluence.
  • If you store attachments on external WebDAV servers, we recommend that you migrate to file-system or database-backed attachment storage as soon as possible. Refer to CONF-9313 and CONF-2887.
  • This DOES NOT affect the operation of the WebDAV plugin.

Migration between Attachment Storage Systems

You can 'migrate' your attachments from one storage system to another. All existing attachments will be moved over to the new attachment storage system.

Icon

When the migration occurs, all other users will be locked out of the Confluence instance. This is to prevent modification of attachments while the migration occurs. Access will be restored as soon as the migration is complete.

Icon

When migrating attachments from your database to a filesystem, the attachments are removed from the database after migration. However, when migrating attachments from a filesystem to your database, the attachments remain on the filesystem after migration. If you wish to change this function's behaviour from 'copy' to 'move', please see CONF-14802 and cast your vote.

To perform a migration, follow the steps below:

  1. Choose the cog icon  at top right of the screen, then choose Confluence Admin.
  2. Click 'Attachment Storage' in the left-hand panel. The current configuration will be displayed.
    Screenshot: Attachment storage configuration
  3. Click the 'Edit' button to modify the configuration.
  4. Select the storage system you desire.
    Screenshot: Edit attachment storage
  5. Click the 'Save' button to save the changes.
  6. A screen will appear, asking you to confirm your changes. Clicking 'Migrate' will take you to a screen that displays the progress of the migration.
    Screenshot: migration warning

The following external website provides further information on migrating attachments from database to file system storage that you might find helpful - http://www.scandio.de/2013/05/confluence-attachment-migration-the-safe-way-2/.

Troubleshooting

To enable debug logging for WebDAV attachment storage, add the following to the bottom of WEB-INF/classes/log4j.properties and restart Confluence:

For more about log file configuration, see Working with Confluence Logs.

22 Comments

  1. Is there any way for hosting companies to stop administrators from storing the files in the database? We're moving our database on to a seperate server and having attachments stored in there would be a major nightmare.

    1. You can change the .vm file to remove that option.

      Tom

  2. Has this setup been tried with the mod_dav_svn module in Apache 2.2?  This module provides WebDAV service, where files are stored in a Subversion (version control) repository.  I can configure Confluence (2.3.3) to use this type of WebDAV server for attachment storage, then the migration takes several minutes to run (as expected), but no files show up in the Subversion repository (almost as if the files were transfered but no "commits" never happened). 

    1. Although I haven't tested it, I don't think the WebDAV attachment storage works as you would expect with Subversion as a back-end. I'm basing this on the fact that there's a third-party plugin to provide exactly this functionality, although it's still in the alpha development phase.

      Try adding the extra logging as described in Troubleshooting above. If you think there's a bug in our WebDAV support, please raise a support case, and attach your logs. We'll investigate further from there.

      1. I believe you are correct about SVN+WebDAV - I tried using it that way myself a couple of days ago (in a different context) and it wasn't cooperative.

  3. Really unhappy to see the WebDAV support for attachments being deprecated. My company is currently using the file storage option but we were planning to migrate to WebDAV in the near future.

  4. My confluence installation is on a linux server.  I've created a link for the attachments directory off to an NFS mount point.  It seems to be working just fine.  Has anyone encountered any issues using NFS as an attachments location?

    1. Hi Phil,

      We have not test on such configuration in depth and NFS storage is not a configuration we support. Although, we do have customers using such configuration successfully, a networked filesystem is something we like to eliminate as a potential cause of problems in support cases.
      However, the following could be the potential risks that you might want to consider:

      • Network failure
      • Two separate threads writing to an attachment could cause file corruption. This would mean two separate users writing the same attachment which is probably unlikely, but the risk still exists.

      Hope it helps.

      Cheers,
      Tony

  5. Hi,

    Any recommendations on whether one should use the database for attachment storage (in our case MySQL 5) or the File System (Linux ext3)?

    We currently use the DB and it almost seems that Atlassian recommend this but I've heard people say that storing a lot of data in the DB as BLOBs is not a very good idea.

    Any thoughts?

    Our attachment data is about a GIG in size now.

    My understanding is that MySQL does not have a size limit (other than the limit of the disk it is on) so we'd be happy to keep using it unless it is better to use the FS in the long run.

    I'm not an MySQL expert so I'd appreciate some thoughts from people here.

    Many Thanks

    Semir

    1. It usually has something to do with the backup facilities of your IT Department.

      Not storing the data within your database creates two locations for your backup strategy (Database and File System).
      The backup's of each of these smaller parts are a little bit faster on it's own.

      The attachments could be stored on a NAS Drive which could be easier to implement as extending your DB.

      however,
      Storing everything on the database makes backing it up a little easier for your IT Department, as regular backups should always be performed on all your database content. The procedures are well known and they do not have to be linked to another backup with files from your file system (could be an administrative problem).

      Another reason for storing everything in the database could be a possible future migration to a confluence clustered environment.

      I usually say:
      Do whatever your IT Department thinks is best.
      and
      Use the tools they are most familiar with as there is no big difference.

      1. Anonymous

        Our IT people are telling us that we should see a performance boost (which we really need) by moving the attachments out of the DB and back into the filesystem, particularly as the DB is on a separate Oracle server. Has anyone seen any such improvements in the one over the other in terms of performance?

        1. Hi there,

          Though we don't have a concrete whitepaper to support this, but based on my experience, so far I haven't seen any issue with Confluence due to storing attachments in the file system. In your case however, since your DB is residing on a different machine, do note of the network latency when your Confluence is trying to retrieve/store the attachments, thought it might not be that significant if it is in the same LAN. Other performance gain that I can think of is that it your periodically database backup/dump files will definitely be much smaller.

          hope this helps,
          Henry CL Tiong
          Atlassian Support Team

  6. Is there any issue with attachment size ? Our administrator tells us we should not 'use confluence as Rapidshare', i.e. upload attachments
    larger than say 5 MB. We do use quite some videocasts in our company, so the need for big uploads appears reguralry. We store the attachments in the
    filesystem. Any advice would be welcome. Thanks.

    1. Hi David,

      As far as I know, there should not be any issue regarding attaching a large file size. The only thing that you have to ensure is your local disks have sufficient space.

      Hope that helps.

      Best rgds,
      Zed

  7. Anonymous

    Hi,

    I am interested in the comment above RE NFS - "We have not test on such configuration in depth and NFS storage is not a configuration we support".  Is this statement still true?
    thanks

  8. I am really interested in the NFS thing as well. We are currently implementing a SAN / NAS solution and i am wondering if it is possible to store the attachments in there via NFS?

  9. Anonymous

    Hi,

    Is the performance of the Wiki Server impacted if we attach documents (PDF, doc, ppt etc.) to a wiki page? If yes, in what way the performance will be impacted for example, in terms of high page call-up times, server unavailable error 503 etc.,?

    Can you please share any link where the impact of the wiki server is considerable by having attachments to the Wiki page for a multiple wiki space scenario within the server?

    Thank you in advance. 

  10. Just wanted to share that we got an error message recently. The user was trying to use Insert Link > Attachments to add a file to a page. He got an error "Could not upload the file to Confluence. The server may be unavailable."

    This was misleading because the server (which server by the way?) where the file is stored was accessible as was, obviously, the Confluence server, and less obviously, the attachments storage directory.

    It turned out that it was because the file size of the upload was bigger than the currently configured attachment file size limit.

    We got a clearer error message when uploading via Add > Attachment: "Total upload size is too large (current_upload_limit_in_MB). Reduce total filesize to below current_upload_limit_in_MB."

    The error message in the Insert Link dialog is not helpful.

    1. I have also noticed that a user can log in, attempt to upload an image using the browse capability, it will give the message "Could not upload the file to Confluence. The server may be unavailable."  Though if I drag and drop, it works.

       

  11. How does a migration from filesystem to database happen behind the scenes? Is it one move with a single commit at the end for all of the attachments? Any special steps need to be taken to ensure that a migration of a large amount of data (~500GB) can be accomplished without failing?

    1. In performance wise, would Database perform like filesystem via Tomcat?
    2. If files are stored in Database, who is managing caching of attachments? 
    3. What does it mean by all records?
      1. In Migration Notes in above image, "Prior to migration, all records in the Attachment data database table will be removed."
      2. Does it mean like version history?
    4. What happens during Migration? What will users see during migration? Is server locked down?
    5. Migrating to Database, will it affect WebDav clients or any related feature? 
    6. Can we switch back to Filesystem after migrating to Database?

    Thank you~

     

  12. Anonymous

     

    Hi,

    we have a lot of attachments and to check if they are all actual takes almost two days. The files are on a linux server and if there are made changes on a document it should be also updated in Confluence. That's the theory, in real life the responsible persons make changes and save the document but do not update the file (attachment) in Confluence.

    Is there a way to automation compare the Confluence attachments directly with the files on the server? If you have an other idea, please let me know

    I couldn't found anything in the documentation this is to special.

     

    Many thanks

     

    Randy