docs/frontends/drop-upload.rst

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