docs/frontends/drop-upload.rst

   1 .. -*- coding: utf-8-with-signature -*-
   2
   3 ===============================
   4 Tahoe-LAFS Drop-Upload Frontend
   5 ===============================
   6
   7 1.  `Introduction`_
   8 2.  `Configuration`_
   9 3.  `Known Issues and Limitations`_
  10
  11
  12 Introduction
  13 ============
  14
  15 The drop-upload 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. This is a preview of a feature that we expect to support across
  18 several platforms, but it currently works only on Linux.
  19
  20 The implementation was written as a prototype at the First International
  21 Tahoe-LAFS Summit in June 2011, and is not currently in as mature a state as
  22 the other frontends (web, CLI, SFTP and FTP). This means that you probably
  23 should not keep important data in the upload directory, and should not rely
  24 on all changes to files in the local directory to result in successful uploads.
  25 There might be (and have been) incompatible changes to how the feature is
  26 configured. There is even the possibility that it may be abandoned, for
  27 example if unsolveable reliability issues are found.
  28
  29 We are very interested in feedback on how well this feature works for you, and
  30 suggestions to improve its usability, functionality, and reliability.
  31
  32
  33 Configuration
  34 =============
  35
  36 The drop-upload frontend runs as part of a gateway node. To set it up, you
  37 need to choose the local directory to monitor for file changes, and a mutable
  38 directory on the grid to which files will be uploaded.
  39
  40 These settings are configured in the ``[drop_upload]`` section of the
  41 gateway's ``tahoe.cfg`` file.
  42
  43 ``[drop_upload]``
  44
  45 ``enabled = (boolean, optional)``
  46
  47     If this is ``True``, drop-upload will be enabled. The default value is
  48     ``False``.
  49
  50 ``local.directory = (UTF-8 path)``
  51
  52     This specifies the local directory to be monitored for new or changed
  53     files. If the path contains non-ASCII characters, it should be encoded
  54     in UTF-8 regardless of the system's filesystem encoding. Relative paths
  55     will be interpreted starting from the node's base directory.
  56
  57 In addition, the file  ``private/drop_upload_dircap`` must contain a
  58 writecap pointing to an existing mutable directory to be used as the target
  59 of uploads. It will start with ``URI:DIR2:``, and cannot include an alias
  60 or path.
  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 When a local file is changed and closed several times in quick succession,
 122 it may be uploaded more times than necessary to keep the remote copy
 123 up-to-date. (`#1440`_)
 124
 125 Files deleted from the local directory will not be unlinked from the upload
 126 directory. (`#1710`_)
 127
 128 The ``private/drop_upload_dircap`` file cannot use an alias or path to
 129 specify the upload directory. (`#1711`_)
 130
 131 Files are always uploaded as immutable. If there is an existing mutable file
 132 of the same name in the upload directory, it will be unlinked and replaced
 133 with an immutable file. (`#1712`_)
 134
 135 If a file in the upload directory is changed (actually relinked to a new
 136 file), then the old file is still present on the grid, and any other caps to
 137 it will remain valid. See `docs/garbage-collection.rst`_ for how to reclaim
 138 the space used by files that are no longer needed.
 139
 140 Unicode names are supported, but the local name of a file must be encoded
 141 correctly in order for it to be uploaded. The expected encoding is that
 142 printed by ``python -c "import sys; print sys.getfilesystemencoding()"``.
 143
 144 .. _`#1105`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1105
 145 .. _`#1430`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1430
 146 .. _`#1431`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1431
 147 .. _`#1432`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1432
 148 .. _`#1433`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1433
 149 .. _`#1440`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1440
 150 .. _`#1449`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1449
 151 .. _`#1458`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1458
 152 .. _`#1459`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1459
 153 .. _`#1710`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1710
 154 .. _`#1711`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1711
 155 .. _`#1712`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/1712
 156
 157 .. _docs/garbage-collection.rst: ../garbage-collection.rst
 158