docs/frontends/magic-folder.rst

   1 .. -*- coding: utf-8-with-signature -*-
   2
   3 ================================
   4 Tahoe-LAFS Magic Folder Frontend
   5 ================================
   6
   7 1.  `Introduction`_
   8 2.  `Configuration`_
   9 3.  `Known Issues and Limitations`_
  10
  11
  12 Introduction
  13 ============
  14
  15 The Magic Folder frontend allows an upload to a Tahoe-LAFS grid to be triggered
  16 automatically whenever a file is created or changed in a specific local
  17 directory. It currently works on Linux and Windows.
  18
  19 The implementation was written as a prototype at the First International
  20 Tahoe-LAFS Summit in June 2011, and is not currently in as mature a state as
  21 the other frontends (web, CLI, SFTP and FTP). This means that you probably
  22 should not rely on all changes to files in the local directory to result in
  23 successful uploads. There might be (and have been) incompatible changes to
  24 how the feature is configured.
  25
  26 We are very interested in feedback on how well this feature works for you, and
  27 suggestions to improve its usability, functionality, and reliability.
  28
  29
  30 Configuration
  31 =============
  32
  33 The Magic Folder frontend runs as part of a gateway node. To set it up, you
  34 must use the tahoe magic-folder CLI. For detailed information see our
  35 `Magic-Folder CLI design documentation`_.
  36 need to choose the local directory to monitor for file changes, and a mutable
  37 directory on the grid to which files will be uploaded.
  38
  39 These settings are configured in the ``[magic_folder]`` section of the
  40 gateway's ``tahoe.cfg`` file.
  41
  42 ``[magic_folder]``
  43
  44 ``enabled = (boolean, optional)``
  45
  46     If this is ``True``, Magic Folder will be enabled. The default value is
  47     ``False``.
  48
  49 ``local.directory = (UTF-8 path)``
  50
  51     This specifies the local directory to be monitored for new or changed
  52     files. If the path contains non-ASCII characters, it should be encoded
  53     in UTF-8 regardless of the system's filesystem encoding. Relative paths
  54     will be interpreted starting from the node's base directory.
  55
  56 In addition:
  57  * the file ``private/magic_folder_dircap`` must contain a writecap pointing
  58    to an existing mutable directory to be used as the target of uploads.
  59    It will start with ``URI:DIR2:``, and cannot include an alias or path.
  60  * the file ``private/collective_dircap`` must contain a readcap
  61
  62 After setting the above fields and starting or restarting the gateway,
  63 you can confirm that the feature is working by copying a file into the
  64 local directory. Then, use the WUI or CLI to check that it has appeared
  65 in the upload directory with the same filename. A large file may take some
  66 time to appear, since it is only linked into the directory after the upload
  67 has completed.
  68
  69 The 'Operational Statistics' page linked from the Welcome page shows
  70 counts of the number of files uploaded, the number of change events currently
  71 queued, and the number of failed uploads. The 'Recent Uploads and Downloads'
  72 page and the node log_ may be helpful to determine the cause of any failures.
  73
  74 .. _log: ../logging.rst
  75
  76
  77 Known Issues and Limitations
  78 ============================
  79
  80 This frontend only works on Linux and Windows. There is a ticket to add
  81 support for Mac OS X and BSD-based systems (`#1432`_).
  82
  83 The only way to determine whether uploads have failed is to look at the
  84 'Operational Statistics' page linked from the Welcome page. This only shows
  85 a count of failures, not the names of files. Uploads are never retried.
  86
  87 The Magic Folder frontend performs its uploads sequentially (i.e. it waits
  88 until each upload is finished before starting the next), even when there
  89 would be enough memory and bandwidth to efficiently perform them in parallel.
  90 A Magic Folder upload can occur in parallel with an upload by a different
  91 frontend, though. (`#1459`_)
  92
  93 On Linux, if there are a large number of near-simultaneous file creation or
  94 change events (greater than the number specified in the file
  95 ``/proc/sys/fs/inotify/max_queued_events``), it is possible that some events
  96 could be missed. This is fairly unlikely under normal circumstances, because
  97 the default value of ``max_queued_events`` in most Linux distributions is
  98 16384, and events are removed from this queue immediately without waiting for
  99 the corresponding upload to complete. (`#1430`_)
 100
 101 The Windows implementation might also occasionally miss file creation or
 102 change events, due to limitations of the underlying Windows API
 103 (ReadDirectoryChangesW). We do not know how likely or unlikely this is.
 104 (`#1431`_)
 105
 106 Some filesystems may not support the necessary change notifications.
 107 So, it is recommended for the local directory to be on a directly attached
 108 disk-based filesystem, not a network filesystem or one provided by a virtual
 109 machine.
 110
 111 Attempts to read the mutable directory at about the same time as an uploaded
 112 file is being linked into it, might fail, even if they are done through the
 113 same gateway. (`#1105`_)
 114
 115 When a local file is changed and closed several times in quick succession,
 116 it may be uploaded more times than necessary to keep the remote copy
 117 up-to-date. (`#1440`_)
 118
 119 Files deleted from the local directory will not be unlinked from the upload
 120 directory. (`#1710`_)
 121
 122 The ``private/magic_folder_dircap`` and ``private/collective_dircap`` files
 123 cannot use an alias or path to specify the upload directory. (`#1711`_)
 124
 125 Files are always uploaded as immutable. If there is an existing mutable file
 126 of the same name in the upload directory, it will be unlinked and replaced
 127 with an immutable file. (`#1712`_)
 128
 129 If a file in the upload directory is changed (actually relinked to a new
 130 file), then the old file is still present on the grid, and any other caps to
 131 it will remain valid. See `docs/garbage-collection.rst`_ for how to reclaim
 132 the space used by files that are no longer needed. Garbage collection is
 133 not included as part of the OTF Magic-Folder grant... however we've documented
 134 this feature here `#2440`_
 135
 136 Unicode filenames are supported on both Linux and Windows, but on Linux, the
 137 local name of a file must be encoded correctly in order for it to be uploaded.
 138 The expected encoding is that printed by
 139 ``python -c "import sys; print sys.getfilesystemencoding()"``.
 140
 141 On Windows, local directories with non-ASCII names are not currently working.
 142 (`#2219`_)
 143
 144 On Windows, when a node has Magic Folder enabled, it is unresponsive to Ctrl-C
 145 (it can only be killed using Task Manager or similar). (`#2218`_)
 146
 147 .. _`#1105`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1105
 148 .. _`#1430`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1430
 149 .. _`#1431`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1431
 150 .. _`#1432`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1432
 151 .. _`#1433`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1433
 152 .. _`#1440`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1440
 153 .. _`#1449`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1449
 154 .. _`#1458`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1458
 155 .. _`#1459`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1459
 156 .. _`#1710`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1710
 157 .. _`#1711`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1711
 158 .. _`#1712`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1712
 159 .. _`#2218`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/2218
 160 .. _`#2219`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/2219
 161 .. _`#2440`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/2440
 162
 163 .. _docs/garbage-collection.rst: ../garbage-collection.rst
 164 .. _`Magic-Folder CLI design documentation`: ../proposed/magic-folder/user-interface-design.rst