doc/plugins/attachment.mdwn

   1 [[template id=plugin name=conditional core=1 author="[[Joey]]"]]
   2 [[tag type/useful]]
   3
   4 This plugin allows files to be uploaded to the wiki over the web.
   5
   6 For each page `foo`, files in the subdirectory `foo/` are treated as
   7 attachments of that page. Attachments can be uploaded and managed as
   8 part of the interface for editing a page.
   9
  10 Warning: Do not enable this plugin on publically editable wikis, unless you
  11 take care to lock down the types and sizes of files that can be uploaded.
  12 Bear in mind that if you let anyone upload a particular kind of file
  13 ("*.mp3" files, say), then someone can abuse your wiki in at least three ways:
  14
  15 1. By uploading many mp3 files, wasting your disk space.
  16 2. By uploading mp3 files that attempt to exploit security holes
  17    in web browsers or other players.
  18 3. By uploading files that claim to be mp3 files, but are really some
  19    other kind of file. Some web browsers may display a `foo.mp3` that
  20    contains html as a web page; including running any malicious javascript
  21    embedded in that page.
  22
  23 To provide a way to combat these abuses, the wiki admin can specify a
  24 [[ikiwiki/PageSpec]] on their preferences page, to control what types of
  25 attachments can be uploaded, and by whom. The regular [[ikiwiki/PageSpec]]
  26 syntax is expanded with additional tests.
  27
  28 For example, to limit arbitrary files to 50 kilobytes, but allow
  29 larger mp3 files to be uploaded by joey, a test like this could be
  30 used:
  31
  32         (user(joey) and *.mp3 and mimetype(audio/mpeg) and maxsize(15mb)) or (!ispage() and maxsize(50kb))
  33
  34 The following additional tests are available:
  35
  36 * maxsize(size)
  37
  38   Tests whether the attachment is no larger than the specified size.
  39   The size defaults to being in bytes, but "kb", "mb", "gb" etc can be
  40   used to specify the units.
  41
  42 * minsize(size)
  43
  44   Tests whether the attachment is no smaller than the specified size.
  45
  46 * ispage()
  47
  48   Tests whether the attachment will be treated by ikiwiki as a wiki page.
  49   (Ie, if it has an extension of ".mdwn", or of any other enabled page
  50   format).
  51
  52   So, if you don't want to allow wiki pages to be uploaded as attachments,
  53   use `!ispage()` ; if you only want to allow wiki pages to be uploaded
  54   as attachments, use `ispage()`.
  55
  56 * user(username)
  57
  58   Tests whether the attachment is being uploaded by a user with the
  59   specified username. If openid is enabled, an openid can also be put here.
  60
  61 * ip(address)
  62
  63   Tests whether the attacment is being uploaded from the specified IP
  64   address.
  65
  66 * mimetype(foo/bar)
  67
  68   If the [[cpan File::MimeInfo::Magic]] perl module is installed, this
  69   allows checking the mime type of the attachment. You can include a glob
  70   in the type, for example `mimetype(image/*)`.