Wiki source code of Attachments
Version 27.3 by Ecaterina Moraru (Valica) on 2017/09/06
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
8.1 | 1 | {{box cssClass="floatinginfobox" title="**Contents**"}} |
| 2 | {{toc/}} | ||
| 3 | {{/box}} | ||
| |
5.1 | 4 | |
 |
13.4 | 5 | Attachments can be uploaded either through the regular [[upload action>>platform:Features.Attachments]], [[platform:Features.WebDAV]], [[XML-RPC>>extensions:Extension.XML-RPC Integration]] or [[Rest>>platform:Features.XWikiRESTfulAPI]]. |
| |
1.1 | 6 | As an administrator you can set limits on the maximum size of an attachment and where the attachments will be stored. |
| 7 | |||
| 8 | = Size Limit = | ||
| |
8.1 | 9 | |
 |
10.2 | 10 | The maximum size of an attachment is limited by a configuration parameter in the //XWikiPreferences// document. It is set to about 32MB by default. |
| 11 | To change it follow these steps: | ||
| |
8.1 | 12 | |
| |
10.2 | 13 | 1. Go to //{{{http://<yourwiki>/xwiki/bin/edit/XWiki/XWikiPreferences?editor=object}}}// |
| 14 | 1. Click on the line that says ##XWikiPreferences 0## (right below the line that says ##Objects of type XWiki.XWikiPreferences (1)##) | ||
| 15 | 1. Scroll down to the field that says ##Maximum Upload Size## and change the number to whatever size you want (it is expressed in bytes) | ||
| 16 | 1. Scroll to the bottom and click "Save" | ||
| |
1.1 | 17 | |
 |
22.1 | 18 | {{warning}} |
| |
24.1 | 19 | Note that if you've already tried to attach a file and it failed, in order for the new size setting to be taken into account you might need to clear your browser's cache. |
| |
23.1 | 20 | {{/warning}} |
| |
22.1 | 21 | |
| |
3.1 | 22 | = Versions = |
| |
8.1 | 23 | |
| |
10.2 | 24 | When a user uploads an attachment and then uploads another attachment with the exact same name, you can decide whether or not to keep a version history of the attachments like you do with documents. |
 |
27.3 | 25 | XWiki stores all document attachment versions by default which costs more storage space. If you need only latest versions of attachments, you can disable attachment version control by editing your [[xwiki.cfg>>Documentation.AdminGuide.Configuration#HSamplexwiki.cfg]] and adding: |
| |
3.1 | 26 | |
| |
8.1 | 27 | {{code language="none"}} |
| 28 | xwiki.store.attachment.versioning=0 | ||
| 29 | {{/code}} | ||
| |
3.1 | 30 | |
| 31 | = Deletion = | ||
| |
8.1 | 32 | |
| |
27.3 | 33 | Deleted attachments are stored in a recycle bin so that they can be restored along with the document when rolling back or previewing an earlier version where the attachment should be visible. To disable this feature, edit [[xwiki.cfg>>Documentation.AdminGuide.Configuration#HSamplexwiki.cfg]] and add: |
| |
3.1 | 34 | |
| |
8.1 | 35 | {{code language="none"}} |
| 36 | storage.attachment.recyclebin=0 | ||
| 37 | {{/code}} | ||
| |
3.1 | 38 | |
| |
4.1 | 39 | You can view the list of deleted attachments in your wiki and delete them permanently by going to ##XWiki.DeletedAttachments## in your wiki. |
| |
3.1 | 40 | |
| |
1.1 | 41 | = Attachment Storage = |
| |
8.1 | 42 | |
| |
1.1 | 43 | XWiki offers plugin attachment storage mechanisms so you can store your attachments in the database or directly in the filesystem. |
| 44 | |||
| 45 | No matter what type of attachment store you use, the meta-data for the attachment will be saved in the [[xwikiattachment>>platform:DevGuide.DsXWikiAttachment]] table for faster loads. | ||
| 46 | |||
| 47 | == Database Attachment Store (Default) == | ||
| |
8.1 | 48 | |
| |
10.2 | 49 | This attachment storage mechanism stores your attachments in database entries in the [[xwikiattachment_content>>platform:DevGuide.DsXWikiAttachmentContent]], [[xwikiattachment_archive>>platform:DevGuide.XWikiAttachmentArchive]] and [[xwikiattrecyclebin>>platform:DevGuide.DsXwikiRecycleBin]] tables. This system allows for easy backup of your attachments by dumping the database and keeping all of your data together, but attachment size is memory constrained since the attachment content and archive must all be held in memory. As a general rule, attachments larger than 30MB are not possible. |
| |
1.1 | 50 | |
| |
10.2 | 51 | {{info}} |
| |
27.3 | 52 | When using this attachment store with a MySQL database, you must set the ##max_allowed_packet## to about 3 times the size of your largest attachment since the attachment and its version history must be saved. See the [[MySQL Installation guide>>Documentation.AdminGuide.InstallationMySQL]] for more information. |
| |
10.2 | 53 | {{/info}} |
| 54 | |||
| |
11.1 | 55 | == Filesystem Attachment Store == |
| |
1.1 | 56 | |
| |
10.2 | 57 | The Filesystem attachment store saves your attachments in files in a directory tree. This means you will have one more thing to do when you back up your data but it also means you can save larger (over one gigabyte) files. Filesystem attachment store implements a two stage commit mechanism to maintain integrity even if the database fails to commit the attachment meta-data. |
| |
10.1 | 58 | |
| |
12.1 | 59 | {{error}} |
 |
20.1 | 60 | There is a [[bug>>https://jira.xwiki.org/browse/XWIKI-9065]] in XWiki, that prevents restoring attachments from the recycle bin via UI: you will find empty LiveTable. Attachment delete action brings new version to the document, so, the correct way to restore the attachment is to rollback to the necessary version. If you delete the document with the attachment and then click delete again to permanently expunge the document from history, the attachment will be removed from your system together |
| |
13.1 | 61 | One of the options to avoid mess with attachments in the filesystem until this bug would be fixed, just turn off recycle bin for attachments at all. |
| |
12.1 | 62 | {{/error}} |
| 63 | |||
| |
18.1 | 64 | === Enabling Filesystem attachment store === |
| |
12.1 | 65 | |
| |
18.1 | 66 | ==== New users ==== |
| 67 | |||
| |
27.3 | 68 | If you are a new XWiki user, all you need to do for enabling Filesystem Attachment Store is to change some settings in the [[xwiki.cfg>>Documentation.AdminGuide.Configuration#HSamplexwiki.cfg]] file. |
| |
18.1 | 69 | |
| 70 | These settings should read as follows: | ||
| 71 | |||
| 72 | {{code language="none"}} | ||
| 73 | xwiki.store.attachment.hint = file | ||
| 74 | xwiki.store.attachment.versioning.hint = file | ||
| 75 | xwiki.store.attachment.recyclebin.hint = file | ||
| |
26.1 | 76 | |
| |
25.1 | 77 | # Attachments being also stored in the deleted documents it's safer to also enable filesystem storage for it too |
| 78 | xwiki.store.recyclebin.content.hint = file | ||
| |
18.1 | 79 | {{/code}} |
| 80 | |||
| 81 | Also make sure they are not commented out. | ||
| 82 | |||
| |
19.1 | 83 | {{info}} |
| 84 | If you're using the standalone packaging (the ZIP or EXE packagings) then you already have wiki pages and attachments in the database (since database is the default at the moment). Thus you'll need to apply the instructions for the next section and run the Filesystem Attachment Porter. | ||
| 85 | |||
| 86 | Also note that if have already started XWiki and executed the Distribution Wizard that will have populated your wiki with wiki pages and attachments stored in the database too. So similarly you'll need to apply what's in the next section. | ||
| 87 | {{/info}} | ||
| 88 | |||
| |
18.1 | 89 | ==== Users who already have a running wiki ==== |
| 90 | |||
| 91 | If you already have a wiki and want to take advantage of the Filesystem Attachment Store, you should use the [[snippets:Extension.Filesystem Attachment Porter]] to move your existing attachments onto the filesystem. | ||
| 92 | |||
| |
8.1 | 93 | === Filesystem attachment store location === |
| 94 | |||
| |
10.2 | 95 | The directory in which the attachments are stored in the filesystem is defined with the parameter ##environment.permanentDirectory## in the ##xwiki.properties## file. By default it's defined to be ##data##, which is a directory relative to where the Java Servlet Container was started. It's recommend to modify this value to be absolute sure that you can start the Servlet Container from any directory and still have XWiki find the attachments located in this work directory. |
| |
8.1 | 96 | |
| |
9.2 | 97 | For example: |
| |
8.1 | 98 | |
| 99 | {{code}} | ||
 |
9.6 | 100 | environment.permanentDirectory=/opt/tomcat6/data |
| |
8.1 | 101 | {{/code}} |
| 102 | |||
| |
1.1 | 103 | === Directory Structure === |
| 104 | |||
| |
8.1 | 105 | [[image:FilesystemAttachmentStoreDirtree.png||height="300px"]] |
| |
1.1 | 106 | |
| 107 | The Filesystem Attachment Store puts your attachments into a directory tree on the hard disk, the directory structure is designed to be intuitive to navigate but you should **never add or remove anything**. Each attachment is accompanied by a piece of meta-data in the database and modifying the content in the filesystem store manually will lead to meta-data with no content or content with no meta-data. | ||
| 108 | |||
| 109 | === Other considerations === | ||
| |
8.1 | 110 | |
| |
27.3 | 111 | If you are running a [[cluster>>Documentation.AdminGuide.Clustering]] you will need to have a synchronized storage directory for each node. You can use NFS or other means to mount the disk on each node in the cluster. |
 |
13.2 | 112 | |
| 113 | ==== Directory cleanup ==== | ||
| 114 | |||
| |
27.1 | 115 | Since [[XWiki 6.0M2>>xwiki:ReleaseNotes.ReleaseNotesXWiki61M2]], it is possible to save time on startup by preventing XWiki from cleaning up empty directories in the Filesystem Attachment Store. To do this, edit ##xwiki.properties## and set **store.fsattach.cleanOnStartup** to false. If you do this, you will be responsible for cleanup of empty directories yourself. |
