Wiki source code of Attachments
Last modified by Clemens Robbenhaar on 2025/12/03 16:44
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | {{box cssClass="floatinginfobox" title="**Contents**"}} | ||
| 2 | {{toc/}} | ||
| 3 | {{/box}} | ||
| 4 | |||
| 5 | Attachments can be uploaded either through the regular [[upload action>>Documentation.UserGuide.Features.Attachments]], or via the [[Rest API>>Documentation.UserGuide.Features.XWikiRESTfulAPI]]. | ||
| 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 = | ||
| 9 | |||
| 10 | The maximum size of an attachment is limited by a configuration parameter in the //XWikiPreferences// document. It is set to 100GB by default (32MB for XWiki < 10.9RC1). | ||
| 11 | To change it follow these steps: | ||
| 12 | |||
| 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" | ||
| 17 | 1. Repeat for each (sub)wiki for which you need to increase the size, since currrently this configuration has to be set per wiki | ||
| 18 | |||
| 19 | {{warning}} | ||
| 20 | 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. | ||
| 21 | {{/warning}} | ||
| 22 | |||
| 23 | = Mimetype Restriction = | ||
| 24 | |||
| 25 | See [[Attachent Validation Application>>extensions:Extension.Attachment.Validation.UI.WebHome]]. | ||
| 26 | |||
| 27 | = Versions = | ||
| 28 | |||
| 29 | 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. | ||
| 30 | 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: | ||
| 31 | |||
| 32 | {{code language="none"}} | ||
| 33 | xwiki.store.attachment.versioning=0 | ||
| 34 | {{/code}} | ||
| 35 | |||
| 36 | = Deletion = | ||
| 37 | |||
| 38 | 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: | ||
| 39 | |||
| 40 | {{code language="none"}} | ||
| 41 | storage.attachment.recyclebin=0 | ||
| 42 | {{/code}} | ||
| 43 | |||
| 44 | You can view the list of deleted attachments in your wiki and delete them permanently by going to ##XWiki.DeletedAttachments## in your wiki. | ||
| 45 | |||
| 46 | By default, a deleted document can be permanently deleted right away by administrators, and after 7 days by regular users. To change these limits, edit ##xwiki.cfg## and add: | ||
| 47 | |||
| 48 | {{code language="none"}} | ||
| 49 | # Admins must wait 3 days before being allowed to permanently delete | ||
| 50 | xwiki.store.recyclebin.adminWaitDays=3 | ||
| 51 | # Normal users must also wait 3 days | ||
| 52 | xwiki.store.recyclebin.waitDays=3 | ||
| 53 | {{/code}} | ||
| 54 | |||
| 55 | = Attachment Storage = | ||
| 56 | |||
| 57 | XWiki offers plugin attachment storage mechanisms so you can store your attachments in the database or directly in the filesystem. | ||
| 58 | |||
| 59 | Generally metadata for attachment and deleted attachments stay in the database whatever store is used for the content. The metadata contains the type of store used for the content allowing each attachment to choose a different store. The consequence is that what you configure is the **default** store for a new attachment and not the store used for all attachments. | ||
| 60 | |||
| 61 | == Filesystem Attachment Store == | ||
| 62 | |||
| 63 | {{version since="10.5"}} | ||
| 64 | The default. | ||
| 65 | {{/version}} | ||
| 66 | |||
| 67 | 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. | ||
| 68 | |||
| 69 | See [[Documentation.AdminGuide.Store.Filesystem]] for more details about the XWiki Filesystem Store in general. | ||
| 70 | |||
| 71 | === Filesystem attachment store location === | ||
| 72 | |||
| 73 | By default the filsystem storage is located in a sub-folder ({{version since="11.0"}}##store/file##{{/version}} or {{version before="11.0"}}##storage##{{/version}}) of the permanent directory (defined with the parameter ##environment.permanentDirectory## in the ##xwiki.properties## file). By default, the permanent directory ends up in the application server work directory, which is intended to be a temporary directory, so unless you are using a package that takes care of it for you (like the Debian package), it's highly recommended to set this value explicitly to be absolutely sure it's located in a safe location. | ||
| 74 | |||
| 75 | For example: | ||
| 76 | |||
| 77 | {{code}} | ||
| 78 | environment.permanentDirectory=/var/lib/xwiki/data | ||
| 79 | {{/code}} | ||
| 80 | |||
| 81 | {{version since="11.4"}} | ||
| 82 | It's possible to set the location of the filesystem store without modifying the general permanent directory using property ##store.file.directory## of the file ##xwiki.properties##. | ||
| 83 | |||
| 84 | {{code}} | ||
| 85 | store.file.directory=/my/custom/location | ||
| 86 | {{/code}} | ||
| 87 | {{/version}} | ||
| 88 | |||
| 89 | === Format === | ||
| 90 | |||
| 91 | Like the database, the filesystem store is based on entities (wiki, document, etc.). To reduce potential problems with very restrictive (in terms of supported encoding and path size) filesystems the paths is hashed. | ||
| 92 | |||
| 93 | For example the attachment in document is stored in the following location: | ||
| 94 | |||
| 95 | ##<databae name>/<first character of the document reference hash>/<second character of the document reference hash>/<remaining characters of the document reference hash>/attachments/<first character of the attachment name hash>/<second character of the attachment name hash>/<remaining characters of the attachment name hash>/f.<ext>## | ||
| 96 | |||
| 97 | * xwiki | ||
| 98 | ** 0 | ||
| 99 | *** 1 | ||
| 100 | **** 42dd85f30db08e0b07a656e2fd6160 | ||
| 101 | ***** attachments | ||
| 102 | ****** c | ||
| 103 | ******* c | ||
| 104 | ******** 35d4b8e796c869289176c383aa3da3 | ||
| 105 | ********* f.lnk | ||
| 106 | ********* fv1.1.png | ||
| 107 | *** 7 | ||
| 108 | **** d993d3bfbf84d0bbf1957f33d6cc93 | ||
| 109 | ***** attachments | ||
| 110 | ****** 1 | ||
| 111 | ******* 5 | ||
| 112 | ******** fd58c6652b9302978713b8a8ef2a39 | ||
| 113 | ********* f.lnk | ||
| 114 | ********* fv1.1.png | ||
| 115 | |||
| 116 | === Other considerations === | ||
| 117 | |||
| 118 | If you are running a [[cluster>>Documentation.AdminGuide.Clustering.WebHome]] 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. | ||
| 119 | |||
| 120 | ==== Directory cleanup ==== | ||
| 121 | |||
| 122 | {{version since="6.0"}} | ||
| 123 | 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. | ||
| 124 | {{/version}} | ||
| 125 | |||
| 126 | == Database Attachment Store == | ||
| 127 | |||
| 128 | {{version before="10.5"}} | ||
| 129 | The default. | ||
| 130 | {{/version}} | ||
| 131 | |||
| 132 | This attachment storage mechanism stores your attachments in database entries in the [[xwikiattachment_content>>Documentation.DevGuide.DsXWikiAttachmentContent]], [[xwikiattachment_archive>>Documentation.DevGuide.XWikiAttachmentArchive]] and [[xwikiattrecyclebin>>Documentation.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. | ||
| 133 | |||
| 134 | === Switch to database attachment store === | ||
| 135 | |||
| 136 | These settings should read as follows: | ||
| 137 | |||
| 138 | {{code language="none"}} | ||
| 139 | xwiki.store.attachment.hint = hibernate | ||
| 140 | xwiki.store.attachment.versioning.hint = hibernate | ||
| 141 | xwiki.store.attachment.recyclebin.content.hint=hibernate | ||
| 142 | |||
| 143 | # If you need to use database store for the attachment it's probably true for deleted attachments | ||
| 144 | xwiki.store.recyclebin.content.hint = hibernate | ||
| 145 | {{/code}} | ||
| 146 | |||
| 147 | Also make sure they are not commented out. | ||
| 148 | |||
| 149 | {{info}} | ||
| 150 | 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. | ||
| 151 | {{/info}} | ||
| 152 | |||
| 153 | = Attachment display or download = | ||
| 154 | |||
| 155 | When possible (see [[Security section>>#HSecurity]] below) attachments are displayed directly in the browser when accessed. | ||
| 156 | It is possible for developers to force-downloading an attachment by adding the parameter ##?force-download=1## in the attachment URL. | ||
| 157 | |||
| 158 | {{version since="12.10"}} | ||
| 159 | it's possible to use a dedicated property in ##xwiki.properties## to always force some attachment mime-types to be downloaded: | ||
| 160 | |||
| 161 | {{code language="none"}} | ||
| 162 | #-# [Since 12.10] | ||
| 163 | #-# Define the kind of attachment that you always want to be downloaded and never displayed inline. | ||
| 164 | #-# By default this list is empty, but you can specify a list of mime-types (coma separated list of values) which | ||
| 165 | #-# should be always downloaded no matter who attached them or what is the whitelist/blacklist configuration. | ||
| 166 | #-# | ||
| 167 | #-# The distinction with the blacklist configuration above is that the blacklist won't affect file attached by a user | ||
| 168 | #-# with programming rights, while this configuration affect any attachment. | ||
| 169 | # attachment.download.forceDownload= | ||
| 170 | {{/code}} | ||
| 171 | {{/version}} | ||
| 172 | |||
| 173 | = Upload summary = | ||
| 174 | |||
| 175 | {{version since="16.3.0RC1"}} | ||
| 176 | You can enable upload summaries in ##xwiki.properties## to let users add descriptions during attachment uploads. | ||
| 177 | |||
| 178 | {{code language="none"}} | ||
| 179 | #-# [Since 16.3.0RC1] | ||
| 180 | #-# Indicate whether or not comments for attachment uploads should be settable from UI, and displayed whenever the | ||
| 181 | #-# attachment revisions are listed. The default is false. | ||
| 182 | # attachment.upload.enableComments=false | ||
| 183 | {{/code}} | ||
| 184 | {{/version}} | ||
| 185 | |||
| 186 | = Security = | ||
| 187 | |||
| 188 | In order to prevent attacks by using attachments, it's possible to control which attachments' can be directly opened on the browser based on their mimetypes. | ||
| 189 | Two properties in ##xwiki.properties## allow to control that independently: | ||
| 190 | |||
| 191 | {{code language="none"}} | ||
| 192 | #-# [Since 5.2M2] | ||
| 193 | #-# Define the kind of attachment that can be displayed inline. You can either choose to do it through a whitelist | ||
| 194 | #-# (only the mimetypes defined in this list would be displayed inline) or a blacklist (every mimetype that is not in | ||
| 195 | #-# this list would be displayed inline if possible). | ||
| 196 | #-# Note that only one configuration is used between the whitelist and the blacklist, and the whitelist always have | ||
| 197 | #-# the priority over the blacklist. Also note that these configurations exist for security reason so they are only | ||
| 198 | #-# impacting attachments added by users who do not have programming rights. | ||
| 199 | #-# If you want to force downloading some attachments types please check the configuration below. | ||
| 200 | #-# | ||
| 201 | #-# By default we use the following whitelist (coma separated list of values). | ||
| 202 | # attachment.download.whitelist=audio/basic,audio/L24,audio/mp4,audio/mpeg,audio/ogg,audio/vorbis,audio/vnd.rn-realaudio,audio/vnd.wave,audio/webm,image/gif,image/jpeg,image/pjpeg,image/png,image/tiff,text/csv,text/plain,text/xml,text/rtf,video/mpeg,video/ogg,video/quicktime,video/webm,video/x-matroska,video/x-ms-wmv,video/x-flv | ||
| 203 | #-# | ||
| 204 | #-# If you prefer to use a blacklist instead, you can define the forbidden types here, as a coma separated list of | ||
| 205 | #-# values. We advise you to forbid at least the following mimetypes : text/html, text/javascript | ||
| 206 | # attachment.download.blacklist=text/html,text/javascript | ||
| 207 | {{/code}} |
