ExternalVendorCode/tahoe-lafs
1
0
Fork 0
mirror of https://github.com/tahoe-lafs/tahoe-lafs.git synced 2025-03-03 12:56:58 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Update hyperlinks between docs, and linkify some external references. refs #1225

Browse Source
This commit is contained in:
david-sarah 2010-12-11 21:14:59 -08:00
parent 458b2de08b
commit 5d612c87ab
15 changed files with 69 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
docs/architecture.rst
View File

@ -18,7 +18,7 @@ Tahoe-LAFS Architecture
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.
@ -312,7 +312,7 @@ commercially-run grid for which all of the storage servers are in a colo
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
@ -364,8 +364,8 @@ clients are responsible for renewing their leases on a periodic basis at
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

20
docs/configuration.rst
View File

@ -73,13 +73,13 @@ set the tub.location option described below.
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.
@ -263,7 +263,7 @@ Client Configuration
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)
@ -379,7 +379,7 @@ service.
[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
@ -451,7 +451,7 @@ private/logport.furl
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

13
docs/frontends/CLI.rst
View File

@ -125,12 +125,13 @@ character encoding specified by the current locale.
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

5
docs/frontends/FTP-and-SFTP.rst
View File

@ -196,8 +196,9 @@ entry to be relinked to a different file. Normally, when the path of an
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

36
docs/frontends/webapi.rst
View File

@ -64,14 +64,14 @@ port 3456, on the loopback (127.0.0.1) interface.
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
@ -200,7 +200,7 @@ that file with::
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::
@ -1904,8 +1904,7 @@ Tahoe-1.1; back with Tahoe-1.0 the web client was responsible for serializing
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
@ -1937,16 +1936,17 @@ this file.
(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"

2
docs/helper.rst
View File

@ -11,7 +11,7 @@ Overview
========
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

3
docs/historical/historical_known_issues.txt
View File

@ -7,7 +7,8 @@ http://tahoe-lafs.org/source/tahoe/trunk/docs/historical/historical_known_issues
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 ==

2
docs/historical/peer-selection-tahoe2.txt
View File

@ -1,4 +1,4 @@
= 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.

4
docs/historical/peer-selection.txt
View File

@ -10,8 +10,8 @@ nodes were parts of which cabals.
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.)

6
docs/how_to_make_a_tahoe-lafs_release.rst
View File

@ -1,6 +1,6 @@
[ ] 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
@ -26,7 +26,7 @@
[ ] 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

21
docs/known_issues.rst
View File

@ -16,14 +16,13 @@ Overview
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
================================================
@ -121,16 +120,16 @@ Firefox, Internet Explorer, and Chrome include a "phishing filter" or
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
@ -198,8 +197,8 @@ To disable the filter in Chrome:
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

2
docs/proposed/GridID.txt
View File

@ -180,7 +180,7 @@ some credentials to the storage server to convince it that the client
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.

4
docs/proposed/mutable-DSA.txt
View File

@ -7,8 +7,8 @@ been implemented. Please see mutable-DSA.svg for a quick picture of the
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 ==

8
docs/specifications/uri.rst
View File

@ -82,8 +82,8 @@ of the total number of shares created, and (size) is an ascii decimal
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
@ -141,7 +141,7 @@ The format of the write-cap for mutable files is::
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::
@ -163,7 +163,7 @@ Directory URIs
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

2
docs/stats.rst
View File

@ -297,7 +297,7 @@ keep its FURL consistent). To explicitly control which port it uses, write
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