Overview
========
-(See the docs/specifications directory for more details.)
+(See the `docs/specifications directory <specifications>`_ for more details.)
There are three layers: the key-value store, the filesystem, and the
application.
facility with high interconnect bandwidth. In this case, the helper is placed
in the same facility, so the helper-to-storage-server bandwidth is huge.
-See "helper.txt" for details about the upload helper.
+See `<helper.rst>`_ for details about the upload helper.
The Filesystem Layer
least frequently enough to prevent any of the leases from expiring before the
next renewal pass.
-See docs/garbage-collection.txt for further information, and how to configure
-garbage collection.
+See `<garbage-collection.rst>`_ for further information, and for how to
+configure garbage collection.
File Repairer
web.port = (strports string, optional)
This controls where the node's webserver should listen, providing
- filesystem access and node status as defined in webapi.txt . This file
- contains a Twisted "strports" specification such as "3456" or
- "tcp:3456:interface=127.0.0.1". The 'tahoe create-node' or 'tahoe
- create-client' commands set the web.port to
- "tcp:3456:interface=127.0.0.1" by default; this is overridable by the
- "--webport" option. You can make it use SSL by writing
- "ssl:3456:privateKey=mykey.pem:certKey=cert.pem" instead.
+ filesystem access and node status as defined in `webapi.rst
+ <frontends/webapi.rst>`_. This file contains a Twisted "strports"
+ specification such as "3456" or "tcp:3456:interface=127.0.0.1".
+ The 'tahoe create-node' or 'tahoe create-client' commands set the
+ web.port to "tcp:3456:interface=127.0.0.1" by default; this is
+ overridable by the "--webport" option. You can make it use SSL by
+ writing "ssl:3456:privateKey=mykey.pem:certKey=cert.pem" instead.
If this is not provided, the node will not run a web server.
helper.furl = (FURL string, optional)
If provided, the node will attempt to connect to and use the given helper
- for uploads. See docs/helper.txt for details.
+ for uploads. See `<helper.rst>`_ for details.
key_generator.furl = (FURL string, optional)
[helper]
enabled = (boolean, optional)
- If True, the node will run a helper (see docs/helper.txt for details).
+ If True, the node will run a helper (see `<helper.rst>`_ for details).
The helper's contact FURL will be placed in private/helper.furl, from
which it can be copied to any clients which wish to use it. Clearly nodes
should not both run a helper and attempt to use one: do not create both
private/helper.furl
if the node is running a helper (for use by other clients), its contact
- FURL will be placed here. See docs/helper.txt for more details.
+ FURL will be placed here. See `<helper.rst>`_ for more details.
private/root_dir.cap (optional)
The command-line tools will read a directory cap out of this file and use
Starting Directories
--------------------
-As described in architecture.txt, the Tahoe distributed filesystem consists
-of a collection of directories and files, each of which has a "read-cap" or a
-"write-cap" (also known as a URI). Each directory is simply a table that maps
-a name to a child file or directory, and this table is turned into a string
-and stored in a mutable file. The whole set of directory and file "nodes" are
-connected together into a directed graph.
+As described in `docs/architecture.rst <../architecture.rst>`_, the
+Tahoe-LAFS distributed filesystem consists of a collection of directories
+and files, each of which has a "read-cap" or a "write-cap" (also known as
+a URI). Each directory is simply a table that maps a name to a child file
+or directory, and this table is turned into a string and stored in a
+mutable file. The whole set of directory and file "nodes" are connected
+together into a directed graph.
To use this collection of files and directories, you need to choose a
starting point: some specific directory that we will refer to as a
immutable file is opened for writing by SFTP, the directory entry is
relinked to another file with the newly written contents when the file
handle is closed. The old file is still present on the grid, and any other
-caps to it will remain valid. (See docs/garbage-collection.txt for how to
-reclaim the space used by files that are no longer needed.)
+caps to it will remain valid. (See `docs/garbage-collection.rst
+<../garbage-collection.rst>`_ for how to reclaim the space used by files
+that are no longer needed.)
The 'no-write' metadata field of a directory entry can override this
behaviour. If the 'no-write' field holds a true value, then a permission
Basic Concepts: GET, PUT, DELETE, POST
======================================
-As described in `architecture.rst`_, each file and directory in a Tahoe virtual
-filesystem is referenced by an identifier that combines the designation of
-the object with the authority to do something with it (such as read or modify
-the contents). This identifier is called a "read-cap" or "write-cap",
-depending upon whether it enables read-only or read-write access. These
-"caps" are also referred to as URIs.
-
-.. _architecture.rst: http://tahoe-lafs.org/source/tahoe-lafs/trunk/docs/architecture.rst
+As described in `docs/architecture.rst <../architecture.rst>`_, each file
+and directory in a Tahoe virtual filesystem is referenced by an identifier
+that combines the designation of the object with the authority to do something
+with it (such as read or modify the contents). This identifier is called a
+"read-cap" or "write-cap", depending upon whether it enables read-only or
+read-write access. These "caps" are also referred to as URIs (which may be
+confusing because they are not currently `RFC3986
+<http://tools.ietf.org/html/rfc3986>`_-compliant URIs).
The Tahoe web-based API is "REST-ful", meaning it implements the concepts of
"REpresentational State Transfer": the original scheme by which the World
Multiple levels of subdirectories can be handled this way::
- http://127.0.0.1:3456/uri/$DIRCAP/tahoe-source/docs/webapi.txt
+ http://127.0.0.1:3456/uri/$DIRCAP/tahoe-source/docs/architecture.rst
In this document, when we need to refer to a URL that references a file using
this child-of-some-directory format, we'll use the following string::
web requests themselves).
For more details, please see the "Consistency vs Availability" and "The Prime
-Coordination Directive" sections of mutable.txt, in the same directory as
-this file.
+Coordination Directive" sections of `mutable.rst <../specifications/mutable.rst>`_.
.. [1] URLs and HTTP and UTF-8, Oh My
(note, the last four bytes of that line, not including the newline, are
0xC3 0xA9 0x65 0x22)
- RFC2231#4 (dated 1997): suggests that the following might work, and some
- developers (http://markmail.org/message/dsjyokgl7hv64ig3) have reported that
- it is supported by firefox (but not IE7)::
+ `RFC2231#4 <http://tools.ietf.org/html/rfc2231#section-4>`_
+ (dated 1997): suggests that the following might work, and
+ `some developers have reported <http://markmail.org/message/dsjyokgl7hv64ig3>`_
+ that it is supported by firefox (but not IE7)::
#2: Content-Disposition: attachment; filename*=utf-8''fianc%C3%A9e
- My reading of RFC2616#19.5.1 (which defines Content-Disposition) says that
- the filename= parameter is defined to be wrapped in quotes (presumeably to
- allow spaces without breaking the parsing of subsequent parameters), which
- would give us::
+ My reading of `RFC2616#19.5.1 <http://tools.ietf.org/html/rfc2616#section-19.5.1>`_
+ (which defines Content-Disposition) says that the filename= parameter is
+ defined to be wrapped in quotes (presumably to allow spaces without breaking
+ the parsing of subsequent parameters), which would give us::
#3: Content-Disposition: attachment; filename*=utf-8''"fianc%C3%A9e"
========
As described in the "SWARMING DOWNLOAD, TRICKLING UPLOAD" section of
-architecture.txt, Tahoe uploads require more bandwidth than downloads: you
+`<architecture.rst>`_, Tahoe uploads require more bandwidth than downloads: you
must push the redundant shares during upload, but you do not need to retrieve
them during download. With the default 3-of-10 encoding parameters, this
means that an upload will require about 3.3x the traffic as a download of the
Issues in newer releases of Tahoe-LAFS can be found at:
-http://tahoe-lafs.org/source/tahoe/trunk/docs/known_issues.txt
+http://tahoe-lafs.org/source/tahoe/trunk/docs/known_issues.rst
+
== issues in Tahoe v1.1.0, released 2008-06-11 ==
-= THIS PAGE DESCRIBES HISTORICAL DESIGN CHOICES. SEE docs/architecture.txt FOR CURRENT DOCUMENTATION =
+= THIS PAGE DESCRIBES HISTORICAL DESIGN CHOICES. SEE docs/architecture.rst FOR CURRENT DOCUMENTATION =
When a file is uploaded, the encoded shares are sent to other peers. But to
which ones? The PeerSelection algorithm is used to make this choice.
When we release 0.2.0, we used the "tahoe3" algorithm (see
peer-selection-tahoe3.txt), but in v0.6 (ticket #132) we switched back to
-"tahoe2" (see the peer-selection-tahoe2.txt, and the PEER SELECTION section
-of docs/architecture.txt), which uses a permuted peerid list and packs the
+"tahoe2" (see peer-selection-tahoe2.txt, and the PEER SELECTION section
+of docs/architecture.rst), which uses a permuted peerid list and packs the
shares into the first 10 or so members of this list. (It is named "tahoe2"
because it was designed before "tahoe3" was.)
-[ ] 1 update doc files: relnotes.txt, CREDITS, docs/known_issues.rst, NEWS. Add release name and date to top-most item in NEWS.
+[ ] 1 update doc files: `<../relnotes.txt>`_, `<../CREDITS>`_, `<known_issues.rst>`_, `<../NEWS>`_. Add release name and date to top-most item in NEWS.
-[ ] 2 change docs/quickstart.html to point to just the current allmydata-tahoe-X.Y.Z.zip source code file, or else to point to a directory which contains only allmydata-tahoe-X.Y.Z.* source code files
+[ ] 2 change `<quickstart.html>`_ to point to just the current allmydata-tahoe-X.Y.Z.zip source code file, or else to point to a directory which contains only allmydata-tahoe-X.Y.Z.* source code files
[ ] 3 darcs pull
[ ] 14 send out relnotes.txt: [ ] tahoe-announce@tahoe-lafs.org, [ ] tahoe-dev@tahoe-lafs.org, [ ] p2p-hackers@lists.zooko.com, [ ] lwn@lwn.net, [ ] cap-talk@mail.eros-os.org, [ ] cryptography@metzdown.com, [ ] cryptography@randombit.net, [ ] twisted-python@twistedmatrix.com, [ ] owncloud@kde.org, [ ] liberationtech@lists.stanford.edu, [ ] the "decentralization" group on groups.yahoo.com, [ ] pycrypto mailing list, -> fuse-devel@lists.sourceforge.net, -> fuse-sshfs@lists.sourceforge.net, [ ] duplicity-talk@nongnu.org, [ ] news@phoronix.com, [ ] python-list@python.org, -> cygwin@cygwin.com, [ ] The Boulder Linux Users' Group, [ ] The Boulder Hackerspace mailing list, [ ] cryptopp-users@googlegroups.com, [ ] tiddlywiki, [ ] hdfs-dev@hadoop.apache.org, [ ] bzr, [ ] mercurial, [ ] http://listcultures.org/pipermail/p2presearch_listcultures.org/ , deltacloud, libcloud, [ ] swift@lists.launchpad.net, cleversafe.org, [ ] stephen@fosketts.net, [ ] Chris Mellor of The Register, [ ] nosql@mypopescu.com
-[ ] 15 update hacktahoe.org
+[ ] 15 update `<http://tahoe-lafs.org/hacktahoelafs/>`_
[ ] 16 make an "announcement of new release" on freshmeat
Below is a list of known issues in recent releases of Tahoe-LAFS, and how to
manage them. The current version of this file can be found at
-
-http://tahoe-lafs.org/source/tahoe-lafs/trunk/docs/known_issues.rst
+`<http://tahoe-lafs.org/source/tahoe-lafs/trunk/docs/known_issues.rst>`_.
If you've been using Tahoe-LAFS since v1.1 (released 2008-06-11) or if you're
just curious about what sort of mistakes we've made in the past, then you might
-want to read the "historical known issues" document:
+want to read `the "historical known issues" document
+<historical/historical_known_issues.txt>`_.
-http://tahoe-lafs.org/source/tahoe-lafs/trunk/docs/historical/historical_known_issues.txt
Issues in Tahoe-LAFS v1.8.1, released 2010-11-28
================================================
any URLs that it deems suspicious to a central server.
Microsoft gives a brief description of their filter's operation at
-<http://blogs.msdn.com/ie/archive/2005/09/09/463204.aspx>. Firefox
+`<http://blogs.msdn.com/ie/archive/2005/09/09/463204.aspx>`_. Firefox
and Chrome both use Google's "safe browsing API" which is documented
-at <http://code.google.com/apis/safebrowsing/> and
-<http://code.google.com/p/google-safe-browsing/wiki/Protocolv2Spec>.
+at `<http://code.google.com/apis/safebrowsing/>`_ and
+`<http://code.google.com/p/google-safe-browsing/wiki/Protocolv2Spec>`_.
This of course has implications for the privacy of general web browsing
(especially in the cases of Firefox and Chrome, which send your main
personally identifying Google cookie along with these requests without
-your explicit consent, as described for Firefox in
-<https://bugzilla.mozilla.org/show_bug.cgi?id=368255>).
+your explicit consent, as described in `Firefox bugzilla ticket #368255
+`<https://bugzilla.mozilla.org/show_bug.cgi?id=368255>`_).
The reason for documenting this issue here, though, is that when using the
Tahoe-LAFS web user interface, it could also affect confidentiality and integrity
Known issues in the FTP and SFTP frontends
------------------------------------------
-These are documented in docs/frontends/FTP-and-SFTP.txt and at
-<http://tahoe-lafs.org/trac/tahoe-lafs/wiki/SftpFrontend>.
+These are documented in `docs/frontends/FTP-and-SFTP.rst <frontends/FTP-and-SFTP.rst>`_
+and at `<http://tahoe-lafs.org/trac/tahoe-lafs/wiki/SftpFrontend>`_.
Traffic analysis based on sizes of files/directories, storage indices, and timing
deserves the space. When storage servers are in this mode, they will have a
certificate that names a public key, and any credentials that can demonstrate
a path from that key will be accepted. This scheme is described in
-docs/accounts-pubkey.txt .
+docs/proposed/old-accounts-pubkey.txt .
The second limitation is unexplored. The read-cap does not currently contain
any notion of who must pay for the bandwidth incurred.
crypto scheme described herein)
This file shows only the differences from RSA-based mutable files to
-(EC)DSA-based mutable files. You have to read and understand mutable.txt before
-reading this file (mutable-DSA.txt).
+(EC)DSA-based mutable files. You have to read and understand
+docs/specifications/mutable.rst before reading this file (mutable-DSA.txt).
== new design criteria ==
representation of the size of the data represented by this URI. All base32
encodings are expressed in lower-case, with the trailing '=' signs removed.
-For example, the following is a CHK URI, generated from the contents of the
-architecture.txt document that lives next to this one in the source tree::
+For example, the following is a CHK URI, generated from a previous version of
+the contents of `<../architecture.rst>`_::
URI:CHK:ihrbeov7lbvoduupd4qblysj7a:bg5agsdt62jb34hxvxmdsbza6do64f4fg5anxxod2buttbo6udzq:3:10:28733
Where (writekey) is the base32 encoding of the 16-byte AES encryption key
that is used to encrypt the RSA private key, and (fingerprint) is the base32
encoded 32-byte SHA-256 hash of the RSA public key. For more details about
-the way these keys are used, please see docs/mutable.txt .
+the way these keys are used, please see `<mutable.rst>`_.
The format for mutable read-caps is::
The grid layer provides a mapping from URI to data. To turn this into a graph
of directories and files, the "vdrive" layer (which sits on top of the grid
layer) needs to keep track of "directory nodes", or "dirnodes" for short.
-docs/dirnodes.txt describes how these work.
+`docs/dirnodes.rst <../dirnodes.rst>`_ describes how these work.
Dirnodes are contained inside mutable files, and are thus simply a particular
way to interpret the contents of these files. As a result, a directory
the desired portnumber into a file named "portnum" (i.e. $BASEDIR/portnum),
and the next time the gatherer is started, it will start listening on the
given port. The portnum file is actually a "strports specification string",
-as described in docs/configuration.txt .
+as described in `docs/configuration.rst <configuration.rst>`_.
Once running, the stats gatherer will create a standard python "pickle" file
in $BASEDIR/stats.pickle . Once a minute, the gatherer will pull stats
projects / tahoe-lafs / tahoe-lafs.git / commitdiff