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 incompatible changes to how the feature is configured in
  24 future versions. 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 (provided that the
  46     ``upload.dircap`` and ``local.directory`` fields are also set). The
  47     default value is ``False``.
  48
  49 ``upload.dircap = (directory writecap)``
  50
  51     This is a writecap pointing to an existing mutable directory to be used
  52     as the target of uploads. It will start with ``URI:DIR2:``, and cannot
  53     include an alias or path.
  54
  55 ``local.directory = (UTF-8 path)``
  56
  57     This specifies the local directory to be monitored for new or changed
  58     files. If the path contains non-ASCII characters, it should be encoded
  59     in UTF-8 regardless of the system's filesystem encoding. Relative paths
  60     will be interpreted starting from the node's base directory.
  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. There is an even-more-experimental
  81 implementation for Windows (`#1431`_), and a ticket to add support for
  82 Mac OS X and BSD-based systems (`#1432`_).
  83
  84 Subdirectories of the local directory are not monitored. If a subdirectory
  85 is created, it will be ignored. (`#1433`_)
  86
  87 If files are created or changed in the local directory just after the gateway
  88 has started, it might not have connected to a sufficient number of servers
  89 when the upload is attempted, causing the upload to fail. (`#1449`_)
  90
  91 Files that were created or changed in the local directory while the gateway
  92 was not running, will not be uploaded. (`#1458`_)
  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 drop-upload 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 drop-upload can occur in parallel with an upload by a different frontend,
 102 though. (`#1459`_)
 103
 104 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 Some filesystems may not support the necessary change notifications.
 113 So, it is recommended for the local directory to be on a directly attached
 114 disk-based filesystem, not a network filesystem or one provided by a virtual
 115 machine.
 116
 117 Attempts to read the mutable directory at about the same time as an uploaded
 118 file is being linked into it, might fail, even if they are done through the
 119 same gateway. (`#1105`_)
 120
 121 Files are always uploaded as immutable. If there is an existing mutable file
 122 of the same name in the upload directory, it will be unlinked and replaced
 123 with an immutable file.
 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
 127 to it will remain valid. See `docs/garbage-collection.rst
 128 <../garbage-collection.rst>`_ for how to reclaim the space used by files
 129 that are no longer needed.
 130
 131 Unicode names are supported, but the local name of a file must be encoded
 132 correctly in order for it to be uploaded. The expected encoding is that
 133 printed by ``python -c "import sys; print sys.getfilesystemencoding()"``.
 134
 135 .. _`#1105`: http://tahoe-lafs.org/trac/tahoe-lafs/ticket/1105
 136 .. _`#1430`: http://tahoe-lafs.org/trac/tahoe-lafs/ticket/1430
 137 .. _`#1431`: http://tahoe-lafs.org/trac/tahoe-lafs/ticket/1431
 138 .. _`#1432`: http://tahoe-lafs.org/trac/tahoe-lafs/ticket/1432
 139 .. _`#1449`: http://tahoe-lafs.org/trac/tahoe-lafs/ticket/1449
 140 .. _`#1458`: http://tahoe-lafs.org/trac/tahoe-lafs/ticket/1458
 141 .. _`#1459`: http://tahoe-lafs.org/trac/tahoe-lafs/ticket/1459