1 .. -*- coding: utf-8-with-signature -*-
3 ================================
4 Tahoe-LAFS Magic Folder Frontend
5 ================================
9 3. `Known Issues and Limitations`_
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.
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.
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.
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`_. For a given Magic-Folder collective
36 directory you need to run the ``tahoe magic-folder create`` command. After that
37 the ``tahoe magic-folder invite`` command must used to generate an invite code for
38 each member of the magic-folder collective. A confidential, authenticated communications
39 channel should be used to transmit the invite code to each member, who will be joining
40 using the ``tahoe magic-folder join`` command.
42 These settings are persisted in the ``[magic_folder]`` section of the
43 gateway's ``tahoe.cfg`` file.
47 ``enabled = (boolean, optional)``
49 If this is ``True``, Magic Folder will be enabled. The default value is
52 ``local.directory = (UTF-8 path)``
54 This specifies the local directory to be monitored for new or changed
55 files. If the path contains non-ASCII characters, it should be encoded
56 in UTF-8 regardless of the system's filesystem encoding. Relative paths
57 will be interpreted starting from the node's base directory.
60 * the file ``private/magic_folder_dircap`` must contain a writecap pointing
61 to an existing mutable directory to be used as the target of uploads.
62 It will start with ``URI:DIR2:``, and cannot include an alias or path.
63 * the file ``private/collective_dircap`` must contain a readcap
65 After setting the above fields and starting or restarting the gateway,
66 you can confirm that the feature is working by copying a file into the
67 local directory. Then, use the WUI or CLI to check that it has appeared
68 in the upload directory with the same filename. A large file may take some
69 time to appear, since it is only linked into the directory after the upload
72 The 'Operational Statistics' page linked from the Welcome page shows
73 counts of the number of files uploaded, the number of change events currently
74 queued, and the number of failed uploads. The 'Recent Uploads and Downloads'
75 page and the node log_ may be helpful to determine the cause of any failures.
77 .. _log: ../logging.rst
80 Known Issues and Limitations
81 ============================
83 This frontend only works on Linux and Windows. There is a ticket to add
84 support for Mac OS X and BSD-based systems (`#1432`_).
86 The only way to determine whether uploads have failed is to look at the
87 'Operational Statistics' page linked from the Welcome page. This only shows
88 a count of failures, not the names of files. Uploads are never retried.
90 The Magic Folder frontend performs its uploads sequentially (i.e. it waits
91 until each upload is finished before starting the next), even when there
92 would be enough memory and bandwidth to efficiently perform them in parallel.
93 A Magic Folder upload can occur in parallel with an upload by a different
94 frontend, though. (`#1459`_)
96 On Linux, if there are a large number of near-simultaneous file creation or
97 change events (greater than the number specified in the file
98 ``/proc/sys/fs/inotify/max_queued_events``), it is possible that some events
99 could be missed. This is fairly unlikely under normal circumstances, because
100 the default value of ``max_queued_events`` in most Linux distributions is
101 16384, and events are removed from this queue immediately without waiting for
102 the corresponding upload to complete. (`#1430`_)
104 The Windows implementation might also occasionally miss file creation or
105 change events, due to limitations of the underlying Windows API
106 (ReadDirectoryChangesW). We do not know how likely or unlikely this is.
109 Some filesystems may not support the necessary change notifications.
110 So, it is recommended for the local directory to be on a directly attached
111 disk-based filesystem, not a network filesystem or one provided by a virtual
114 Attempts to read the mutable directory at about the same time as an uploaded
115 file is being linked into it, might fail, even if they are done through the
116 same gateway. (`#1105`_)
118 When a local file is changed and closed several times in quick succession,
119 it may be uploaded more times than necessary to keep the remote copy
120 up-to-date. (`#1440`_)
122 Files deleted from the local directory will not be unlinked from the upload
123 directory. (`#1710`_)
125 The ``private/magic_folder_dircap`` and ``private/collective_dircap`` files
126 cannot use an alias or path to specify the upload directory. (`#1711`_)
128 Files are always uploaded as immutable. If there is an existing mutable file
129 of the same name in the upload directory, it will be unlinked and replaced
130 with an immutable file. (`#1712`_)
132 If a file in the upload directory is changed (actually relinked to a new
133 file), then the old file is still present on the grid, and any other caps to
134 it will remain valid. See `docs/garbage-collection.rst`_ for how to reclaim
135 the space used by files that are no longer needed. Garbage collection is
136 not included as part of the OTF Magic-Folder grant... however we've documented
137 this feature here `#2440`_
139 Unicode filenames are supported on both Linux and Windows, but on Linux, the
140 local name of a file must be encoded correctly in order for it to be uploaded.
141 The expected encoding is that printed by
142 ``python -c "import sys; print sys.getfilesystemencoding()"``.
144 On Windows, local directories with non-ASCII names are not currently working.
147 On Windows, when a node has Magic Folder enabled, it is unresponsive to Ctrl-C
148 (it can only be killed using Task Manager or similar). (`#2218`_)
150 .. _`#1105`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1105
151 .. _`#1430`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1430
152 .. _`#1431`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1431
153 .. _`#1432`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1432
154 .. _`#1433`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1433
155 .. _`#1440`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1440
156 .. _`#1449`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1449
157 .. _`#1458`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1458
158 .. _`#1459`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1459
159 .. _`#1710`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1710
160 .. _`#1711`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1711
161 .. _`#1712`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1712
162 .. _`#2218`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/2218
163 .. _`#2219`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/2219
164 .. _`#2440`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/2440
166 .. _docs/garbage-collection.rst: ../garbage-collection.rst
167 .. _`Magic-Folder CLI design documentation`: ../proposed/magic-folder/user-interface-design.rst