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