From 1495d0f40553cd2ea4bd97cb7f37cf24632e026d Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Wed, 16 Sep 2015 14:24:10 +0100 Subject: [PATCH] Documentation changes for Magic Folder. Signed-off-by: Daira Hopwood --- .../{drop-upload.rst => magic-folder.rst} | 37 ++++++++++--------- 1 file changed, 19 insertions(+), 18 deletions(-) rename docs/frontends/{drop-upload.rst => magic-folder.rst} (84%) diff --git a/docs/frontends/drop-upload.rst b/docs/frontends/magic-folder.rst similarity index 84% rename from docs/frontends/drop-upload.rst rename to docs/frontends/magic-folder.rst index d7d02831f..93555258a 100644 --- a/docs/frontends/drop-upload.rst +++ b/docs/frontends/magic-folder.rst @@ -1,8 +1,8 @@ .. -*- coding: utf-8-with-signature -*- -=============================== -Tahoe-LAFS Drop-Upload Frontend -=============================== +================================ +Tahoe-LAFS Magic Folder Frontend +================================ 1. `Introduction`_ 2. `Configuration`_ @@ -12,7 +12,7 @@ Tahoe-LAFS Drop-Upload Frontend Introduction ============ -The drop-upload frontend allows an upload to a Tahoe-LAFS grid to be triggered +The Magic Folder frontend allows an upload to a Tahoe-LAFS grid to be triggered automatically whenever a file is created or changed in a specific local directory. It currently works on Linux and Windows. @@ -30,18 +30,18 @@ suggestions to improve its usability, functionality, and reliability. Configuration ============= -The drop-upload frontend runs as part of a gateway node. To set it up, you +The Magic Folder frontend runs as part of a gateway node. To set it up, you need to choose the local directory to monitor for file changes, and a mutable directory on the grid to which files will be uploaded. -These settings are configured in the ``[drop_upload]`` section of the +These settings are configured in the ``[magic_folder]`` section of the gateway's ``tahoe.cfg`` file. -``[drop_upload]`` +``[magic_folder]`` ``enabled = (boolean, optional)`` - If this is ``True``, drop-upload will be enabled. The default value is + If this is ``True``, Magic Folder will be enabled. The default value is ``False``. ``local.directory = (UTF-8 path)`` @@ -51,10 +51,11 @@ gateway's ``tahoe.cfg`` file. in UTF-8 regardless of the system's filesystem encoding. Relative paths will be interpreted starting from the node's base directory. -In addition, the file ``private/drop_upload_dircap`` must contain a -writecap pointing to an existing mutable directory to be used as the target -of uploads. It will start with ``URI:DIR2:``, and cannot include an alias -or path. +In addition: + * the file ``private/magic_folder_dircap`` must contain a writecap pointing + to an existing mutable directory to be used as the target of uploads. + It will start with ``URI:DIR2:``, and cannot include an alias or path. + * the file ``private/collective_dircap`` must contain a readcap After setting the above fields and starting or restarting the gateway, you can confirm that the feature is working by copying a file into the @@ -90,11 +91,11 @@ The only way to determine whether uploads have failed is to look at the 'Operational Statistics' page linked from the Welcome page. This only shows a count of failures, not the names of files. Uploads are never retried. -The drop-upload frontend performs its uploads sequentially (i.e. it waits +The Magic Folder frontend performs its uploads sequentially (i.e. it waits until each upload is finished before starting the next), even when there would be enough memory and bandwidth to efficiently perform them in parallel. -A drop-upload can occur in parallel with an upload by a different frontend, -though. (`#1459`_) +A Magic Folder upload can occur in parallel with an upload by a different +frontend, though. (`#1459`_) On Linux, if there are a large number of near-simultaneous file creation or change events (greater than the number specified in the file @@ -125,8 +126,8 @@ up-to-date. (`#1440`_) Files deleted from the local directory will not be unlinked from the upload directory. (`#1710`_) -The ``private/drop_upload_dircap`` file cannot use an alias or path to -specify the upload directory. (`#1711`_) +The ``private/magic_folder_dircap`` and ``private/collective_dircap`` files +cannot use an alias or path to specify the upload directory. (`#1711`_) Files are always uploaded as immutable. If there is an existing mutable file of the same name in the upload directory, it will be unlinked and replaced @@ -145,7 +146,7 @@ The expected encoding is that printed by On Windows, local directories with non-ASCII names are not currently working. (`#2219`_) -On Windows, when a node has drop-upload enabled, it is unresponsive to Ctrl-C +On Windows, when a node has Magic Folder enabled, it is unresponsive to Ctrl-C (it can only be killed using Task Manager or similar). (`#2218`_) .. _`#1105`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1105