docs/helper.rst

   1 .. -*- coding: utf-8-with-signature -*-
   2
   3 =======================
   4 The Tahoe Upload Helper
   5 =======================
   6
   7 1. `Overview`_
   8 2. `Setting Up A Helper`_
   9 3. `Using a Helper`_
  10 4. `Other Helper Modes`_
  11
  12 Overview
  13 ========
  14
  15 As described in the "Swarming Download, Trickling Upload" section of
  16 `architecture.rst`_, Tahoe uploads require more bandwidth than downloads: you
  17 must push the redundant shares during upload, but you do not need to retrieve
  18 them during download. With the default 3-of-10 encoding parameters, this
  19 means that an upload will require about 3.3x the traffic as a download of the
  20 same file.
  21
  22 .. _architecture.rst: architecture.rst
  23
  24 Unfortunately, this "expansion penalty" occurs in the same upstream direction
  25 that most consumer DSL lines are slow anyways. Typical ADSL lines get 8 times
  26 as much download capacity as upload capacity. When the ADSL upstream penalty
  27 is combined with the expansion penalty, the result is uploads that can take
  28 up to 32 times longer than downloads.
  29
  30 The "Helper" is a service that can mitigate the expansion penalty by
  31 arranging for the client node to send data to a central Helper node instead
  32 of sending it directly to the storage servers. It sends ciphertext to the
  33 Helper, so the security properties remain the same as with non-Helper
  34 uploads. The Helper is responsible for applying the erasure encoding
  35 algorithm and placing the resulting shares on the storage servers.
  36
  37 Of course, the helper cannot mitigate the ADSL upstream penalty.
  38
  39 The second benefit of using an upload helper is that clients who lose their
  40 network connections while uploading a file (because of a network flap, or
  41 because they shut down their laptop while an upload was in progress) can
  42 resume their upload rather than needing to start again from scratch. The
  43 helper holds the partially-uploaded ciphertext on disk, and when the client
  44 tries to upload the same file a second time, it discovers that the partial
  45 ciphertext is already present. The client then only needs to upload the
  46 remaining ciphertext. This reduces the "interrupted upload penalty" to a
  47 minimum.
  48
  49 This also serves to reduce the number of active connections between the
  50 client and the outside world: most of their traffic flows over a single TCP
  51 connection to the helper. This can improve TCP fairness, and should allow
  52 other applications that are sharing the same uplink to compete more evenly
  53 for the limited bandwidth.
  54
  55 Setting Up A Helper
  56 ===================
  57
  58 Who should consider running a helper?
  59
  60 * Benevolent entities which wish to provide better upload speed for clients
  61   that have slow uplinks
  62 * Folks which have machines with upload bandwidth to spare.
  63 * Server grid operators who want clients to connect to a small number of
  64   helpers rather than a large number of storage servers (a "multi-tier"
  65   architecture)
  66
  67 What sorts of machines are good candidates for running a helper?
  68
  69 * The Helper needs to have good bandwidth to the storage servers. In
  70   particular, it needs to have at least 3.3x better upload bandwidth than
  71   the client does, or the client might as well upload directly to the
  72   storage servers. In a commercial grid, the helper should be in the same
  73   colo (and preferably in the same rack) as the storage servers.
  74 * The Helper will take on most of the CPU load involved in uploading a file.
  75   So having a dedicated machine will give better results.
  76 * The Helper buffers ciphertext on disk, so the host will need at least as
  77   much free disk space as there will be simultaneous uploads. When an upload
  78   is interrupted, that space will be used for a longer period of time.
  79
  80 To turn a Tahoe-LAFS node into a helper (i.e. to run a helper service in
  81 addition to whatever else that node is doing), edit the tahoe.cfg file in your
  82 node's base directory and set "enabled = true" in the section named
  83 "[helper]".
  84
  85 Then restart the node. This will signal the node to create a Helper service
  86 and listen for incoming requests. Once the node has started, there will be a
  87 file named private/helper.furl which contains the contact information for the
  88 helper: you will need to give this FURL to any clients that wish to use your
  89 helper.
  90
  91 ::
  92
  93   cat $BASEDIR/private/helper.furl | mail -s "helper furl" friend@example.com
  94
  95 You can tell if your node is running a helper by looking at its web status
  96 page. Assuming that you've set up the 'webport' to use port 3456, point your
  97 browser at ``http://localhost:3456/`` . The welcome page will say "Helper: 0
  98 active uploads" or "Not running helper" as appropriate. The
  99 http://localhost:3456/helper_status page will also provide details on what
 100 the helper is currently doing.
 101
 102 The helper will store the ciphertext that is is fetching from clients in
 103 $BASEDIR/helper/CHK_incoming/ . Once all the ciphertext has been fetched, it
 104 will be moved to $BASEDIR/helper/CHK_encoding/ and erasure-coding will
 105 commence. Once the file is fully encoded and the shares are pushed to the
 106 storage servers, the ciphertext file will be deleted.
 107
 108 If a client disconnects while the ciphertext is being fetched, the partial
 109 ciphertext will remain in CHK_incoming/ until they reconnect and finish
 110 sending it. If a client disconnects while the ciphertext is being encoded,
 111 the data will remain in CHK_encoding/ until they reconnect and encoding is
 112 finished. For long-running and busy helpers, it may be a good idea to delete
 113 files in these directories that have not been modified for a week or two.
 114 Future versions of tahoe will try to self-manage these files a bit better.
 115
 116 Using a Helper
 117 ==============
 118
 119 Who should consider using a Helper?
 120
 121 * clients with limited upstream bandwidth, such as a consumer ADSL line
 122 * clients who believe that the helper will give them faster uploads than
 123   they could achieve with a direct upload
 124 * clients who experience problems with TCP connection fairness: if other
 125   programs or machines in the same home are getting less than their fair
 126   share of upload bandwidth. If the connection is being shared fairly, then
 127   a Tahoe upload that is happening at the same time as a single FTP upload
 128   should get half the bandwidth.
 129 * clients who have been given the helper.furl by someone who is running a
 130   Helper and is willing to let them use it
 131
 132 To take advantage of somebody else's Helper, take the helper furl that they
 133 give you, and edit your tahoe.cfg file. Enter the helper's furl into the
 134 value of the key "helper.furl" in the "[client]" section of tahoe.cfg, as
 135 described in the "Client Configuration" section of configuration.rst_.
 136
 137 .. _configuration.rst: configuration.rst
 138
 139 Then restart the node. This will signal the client to try and connect to the
 140 helper. Subsequent uploads will use the helper rather than using direct
 141 connections to the storage server.
 142
 143 If the node has been configured to use a helper, that node's HTTP welcome
 144 page (``http://localhost:3456/``) will say "Helper: $HELPERFURL" instead of
 145 "Helper: None". If the helper is actually running and reachable, the bullet
 146 to the left of "Helper" will be green.
 147
 148 The helper is optional. If a helper is connected when an upload begins, the
 149 upload will use the helper. If there is no helper connection present when an
 150 upload begins, that upload will connect directly to the storage servers. The
 151 client will automatically attempt to reconnect to the helper if the
 152 connection is lost, using the same exponential-backoff algorithm as all other
 153 tahoe/foolscap connections.
 154
 155 The upload/download status page (``http://localhost:3456/status``) will announce
 156 the using-helper-or-not state of each upload, in the "Helper?" column.
 157
 158 Other Helper Modes
 159 ==================
 160
 161 The Tahoe Helper only currently helps with one kind of operation: uploading
 162 immutable files. There are three other things it might be able to help with
 163 in the future:
 164
 165 * downloading immutable files
 166 * uploading mutable files (such as directories)
 167 * downloading mutable files (like directories)
 168
 169 Since mutable files are currently limited in size, the ADSL upstream penalty
 170 is not so severe for them. There is no ADSL penalty to downloads, but there
 171 may still be benefit to extending the helper interface to assist with them:
 172 fewer connections to the storage servers, and better TCP fairness.
 173
 174 A future version of the Tahoe helper might provide assistance with these
 175 other modes. If it were to help with all four modes, then the clients would
 176 not need direct connections to the storage servers at all: clients would
 177 connect to helpers, and helpers would connect to servers. For a large grid
 178 with tens of thousands of clients, this might make the grid more scalable.