+.. -*- coding: utf-8-with-signature -*-
+
===========================
Garbage Collection in Tahoe
===========================
one or more "leases", which are managed by clients who want the
file/directory to be retained. The storage server accepts each share for a
pre-defined period of time, and is allowed to delete the share if all of the
-leases are cancelled or allowed to expire.
+leases expire.
Garbage collection is not enabled by default: storage servers will not delete
shares without being explicitly configured to do so. When GC is enabled,
There are several tradeoffs to be considered when choosing the renewal timer
and the lease duration, and there is no single optimal pair of values. See
-the `<lease-tradeoffs.svg>`_ diagram to get an idea for the tradeoffs involved.
+the lease-tradeoffs.svg_ diagram to get an idea for the tradeoffs involved.
If lease renewal occurs quickly and with 100% reliability, than any renewal
time that is shorter than the lease duration will suffice, but a larger ratio
of duration-over-renewal-time will be more robust in the face of occasional
delays or failures.
The current recommended values for a small Tahoe grid are to renew the leases
-once a week, and to give each lease a duration of 31 days. Renewing leases
-can be expected to take about one second per file/directory, depending upon
-the number of servers and the network speeds involved. Note that in the
-current release, the server code enforces a 31 day lease duration: there is
-not yet a way for the client to request a different duration (however the
-server can use the "expire.override_lease_duration" configuration setting to
-increase or decrease the effective duration to something other than 31 days).
+once a week, and give each lease a duration of 31 days. In the current
+release, there is not yet a way to create a lease with a different duration,
+but the server can use the ``expire.override_lease_duration`` configuration
+setting to increase or decrease the effective duration (when the lease is
+processed) to something other than 31 days.
+
+Renewing leases can be expected to take about one second per file/directory,
+depending upon the number of servers and the network speeds involved.
+
+.. _lease-tradeoffs.svg: lease-tradeoffs.svg
+
Client-side Renewal
===================
lease too: the ``--add-lease`` process is only needed to ensure that all
older objects have up-to-date leases on them.
-For larger systems (such as a commercial grid), a separate "maintenance
-daemon" is under development. This daemon will acquire manifests from
-rootcaps on a periodic basis, keep track of checker results, manage
-lease-addition, and prioritize repair needs, using multiple worker nodes to
-perform these jobs in parallel. Eventually, this daemon will be made
-appropriate for use by individual users as well, and may be incorporated
-directly into the client node.
+A separate "rebalancing manager/service" is also planned -- see ticket
+`#543`_. The exact details of what this service will do are not settled, but
+it is likely to work by acquiring manifests from rootcaps on a periodic
+basis, keeping track of checker results, managing lease-addition, and
+prioritizing repair and rebalancing of shares. Eventually it may use multiple
+worker nodes to perform these jobs in parallel.
+
+.. _#543: http://tahoe-lafs.org/trac/tahoe-lafs/ticket/543
+
Server Side Expiration
======================
This key is meant to compensate for the fact that clients do not yet have
the ability to ask for leases that last longer than 31 days. A grid which
wants to use faster or slower GC than a 31-day lease timer permits can
- use this parameter to implement it. The current fixed 31-day lease
- duration makes the server behave as if "lease.override_lease_duration =
- 31days" had been passed.
+ use this parameter to implement it.
This key is only valid when age-based expiration is in use (i.e. when
``expire.mode = age`` is used). It will be rejected if cutoff-date
The GC mechanism is also not immediate: a client which deletes a file will
nevertheless be consuming extra disk space (and might be charged or otherwise
held accountable for it) until the ex-file's leases finally expire on their
-own. If the client is certain that they've removed their last reference to
-the file, they could accelerate the GC process by cancelling their lease. The
-current storage server API provides a method to cancel a lease, but the
-client must be careful to coordinate with anyone else who might be
-referencing the same lease (perhaps a second directory in the same virtual
-drive), otherwise they might accidentally remove a lease that should have
-been retained.
+own.
In the current release, these leases are each associated with a single "node
secret" (stored in $BASEDIR/private/secret), which is used to generate
-renewal- and cancel- secrets for each lease. Two nodes with different secrets
-will produce separate leases, and will not be able to renew or cancel each
+renewal-secrets for each lease. Two nodes with different secrets
+will produce separate leases, and will not be able to renew each
others' leases.
Once the Accounting project is in place, leases will be scoped by a