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

replace remaining .html docs with .rst docs

Browse Source 
Remove install.html (long since deprecated).
Also replace some obsolete references to install.html with references to quickstart.rst.
Fix some broken internal references within docs/historical/historical_known_issues.txt.
Thanks to Ravi Pinjala and Patrick McDonald.
refs #1227
This commit is contained in:
Zooko O'Whielacronx 2011-05-10 12:16:50 -07:00
parent 02cfdd2f03
commit 299e8ad579
18 changed files with 381 additions and 338 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CREDITS
View File

@ -94,7 +94,7 @@ P: 0xD5A7EE69911DF5CF
D: port to NetBSD, help debugging Crypto++ bug
N: Sam Mason
D: edited docs/running.html
D: edited docs/running.rst
N: David-Sarah Hopwood
E: david-sarah@jacaranda.org

2
Makefile
View File

@ -77,7 +77,7 @@ endif
signal-error-deps:
@echo
@echo
@echo "ERROR: Not all of Tahoe's dependencies are in place. Please see docs/install.html for help on installing dependencies."
@echo "ERROR: Not all of Tahoe's dependencies are in place. Please see docs/quickstart.rst for help on installing dependencies."
@echo
@echo
exit 1

2
NEWS
View File

@ -428,7 +428,7 @@ Several DeprecationWarnings for python2.6 were silenced. (#859)
The checker --add-lease option would sometimes fail for shares stored
on old (Tahoe v1.2.0) servers. (#875)
The documentation for installing on Windows (docs/install.html) has been
The documentation for installing on Windows (docs/quickstart.rst) has been
improved. (#773)
For other changes not mentioned here, see

4
README.txt
View File

@ -7,7 +7,7 @@ distributes your filesystem across multiple servers, and even if some of the
servers fail or are taken over by an attacker, the entire filesystem continues
to work correctly and to preserve your privacy and security.
To get started please see `quickstart.html`_.
To get started please see `quickstart.rst`_.
LICENCE
=======
@ -22,7 +22,7 @@ the Transitive Grace Period Public Licence, version 1.0.
See `TGPPL.PDF`_ for why the TGPPL exists, graphically illustrated on three slides.
.. _quickstart.html: http://tahoe-lafs.org/source/tahoe-lafs/trunk/docs/quickstart.html
.. _quickstart.rst: http://tahoe-lafs.org/source/tahoe-lafs/trunk/docs/quickstart.rst
.. _COPYING.GPL: http://tahoe-lafs.org/trac/dupfilefind/browser/COPYING.GPL
.. _COPYING.TGPPL.html: http://tahoe-lafs.org/source/dupfilefind/trunk/COPYING.TGPPL.html
.. _TGPPL.PDF: http://tahoe-lafs.org/~zooko/tgppl.pdf

45
docs/about.html
View File

@ -1,45 +0,0 @@
<!DOCtype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html lang="en">
<head>
<title>Welcome To Tahoe-LAFS</title>
<link rev="made" class="mailto" href="mailto:zooko[at]zooko[dot]com">
<meta name="description" content="welcome to Tahoe-LAFS">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="keywords" content="tahoe-lafs secure decentralized filesystem cloud storage">
</head>
<body>
<h1>Welcome to Tahoe-LAFS</h1>
<p>Welcome to <a href="http://tahoe-lafs.org">Tahoe-LAFS</a>, the first decentralized storage system with <cite>provider-independent security</cite>.</p>
<h2>what is "provider-independent security"?</h2>
<p>Every seller of cloud storage services will tell you that their service is "secure". But what they mean by that is something fundamentally different from what we mean. What they mean by "secure" is that after you've given them the power to read and modify your data, they try really hard not to let this power be abused. This turns out to be difficult! Bugs, misconfigurations, or operator error can accidentally expose your data to another customer or to the public, or can corrupt your data. Criminals routinely gain illicit access to corporate servers. Even more insidious is the fact that the employees themselves sometimes violate customer privacy out of carelessness, avarice, or mere curiousity. The most conscientious of these service providers spend considerable effort and expense trying to mitigate these risks.</p>
<p>What we mean by "security" is something different. <em>The service provider never has the ability to read or modify your data in the first place -- never.</em> If you use Tahoe-LAFS, then all of the threats described above are non-issues to you. Not only is it easy and inexpensive for the service provider to maintain the security of your data, but in fact they couldn't violate its security if they tried. This is what we call <em>provider-independent security</em>.</p>
<p>This guarantee is integrated naturally into the Tahoe-LAFS storage system and doesn't require you to perform a manual pre-encryption step or cumbersome key management. (After all, having to do cumbersome manual operations when storing or accessing your data would nullify one of the primary benefits of using cloud storage in the first place -- convenience.)</p>
<p>Here's how it works.</p>
<img src="http://tahoe-lafs.org/~zooko/network-and-reliance-topology.png"></img>
<!-- <p>(See also <a href="http://testgrid.allmydata.org:3567/file/URI:CHK:4rd7ous7b5xgbmpan6mmdbx3za:2jywqfnobreondkanwnekugmxv3cyuzdv34fpyazkb5htjmokdta:3:10:102761/@@named=/network-and-reliance-topology-paranoid.png">Tahoe-LAFS for Paranoids</a> and <a href="http://testgrid.allmydata.org:3567/file/URI:CHK:mpa737uu7suao7lva2axhbtgw4:5rpemho4d3cqsgvgsqmg3hbn2mzeibsbdpthmpyo5jwnj7f2fqfa:3:10:114022/@@named=/network-and-reliance-topology-corporate.png">Tahoe-LAFS for Corporates</a>.)</p> -->
<p>A "storage grid" is made up of a number of storage servers. A storage server has direct attached storage (typically one or more hard disks). A "gateway" uses the storage servers and provides access to the filesystem over HTTP(S) or (S)FTP.</p>
<p>Users do not rely on storage servers to provide <i>confidentiality</i> nor <i>integrity</i> for their data -- instead all of the data is encrypted and integrity-checked by the gateway, so that the servers can neither read nor modify the contents of the files.</p>
<p>Users do rely on storage servers for <i>availability</i>. The ciphertext is erasure-coded and distributed across <cite>N</cite> storage servers (the default value for <cite>N</cite> is 10) so that it can be recovered from any <cite>K</cite> of these servers (the default value of <cite>K</cite> is 3). Therefore only the simultaneous failure of <cite>N-K+1</cite> (with the defaults, 8) servers can make the data unavailable.</p>
<p>In the typical deployment mode each user runs her own gateway on her own machine. This way she relies on her own machine for the confidentiality and integrity of the data.</p>
<p>An alternate deployment mode is that the gateway runs on a remote machine and the user connects to it over HTTPS or SFTP. This means that the operator of the gateway can view and modify the user's data (the user <i>relies on</i> the gateway for confidentiality and integrity), but the advantage is that the user can access the filesystem with a client that doesn't have the gateway software installed, such as an Internet kiosk or cell phone.</p>
<h2>Access control</h2>
<p>There are two kinds of files: immutable and mutable. Immutable files have the property that once they have been uploaded to the storage grid they can't be modified. Mutable ones can be modified. A user can have read-write access to a mutable file or read-only access to it (or no access to it at all).</p>
<p>A user who has read-write access to a mutable file or directory can give another user read-write access to that file or directory, or they can give read-only access to that file or directory. A user who has read-only access to a file or directory can give another user read-only access to it.</p>
<p>When linking a file or directory into a parent directory, you can use a read-write link or a read-only link. If you use a read-write link, then anyone who has read-write access to the parent directory can gain read-write access to the child, and anyone who has read-only access to the parent directory can gain read-only access to the child. If you use a read-only link, then anyone who has either read-write or read-only access to the parent directory can gain read-only access to the child.</p>
<p>For more technical detail, please see the <a href="http://tahoe-lafs.org/trac/tahoe-lafs/wiki/Doc">The Doc Page</a> on the Wiki.</p>
<h2>Get Started</h2>
<p>To use Tahoe-LAFS, please see <a href="quickstart.html">quickstart.html</a>.</p>
<h2>Licence</h2>
<p>You may use this package under the GNU General Public License, version 2 or, at your option, any later version. See the file <a href="../COPYING.GPL">COPYING.GPL</a> for the terms of the GNU General Public License, version 2.</p>
<p>You may use this package under the Transitive Grace Period Public Licence, version 1 or, at your option, any later version. The Transitive Grace Period Public Licence has requirements similar to the GPL except that it allows you to wait for up to twelve months after you redistribute a derived work before releasing the source code of your derived work. See the file <a href="../COPYING.TGPPL.html">COPYING.TGPPL.html</a> for the terms of the Transitive Grace Period Public Licence, version 1.</p>
<p>(You may choose to use this package under the terms of either licence, at your option.)</p>
</body>
</html>

122
docs/about.rst Normal file
View File

@ -0,0 +1,122 @@
======================
Welcome to Tahoe-LAFS!
======================
Welcome to `Tahoe-LAFS <http://tahoe-lafs.org>`_, the first
decentralized storage system with *provider-independent security*.
What is "provider-independent security"?
========================================
Every seller of cloud storage services will tell you that their service
is "secure". But what they mean by that is something fundamentally
different from what we mean. What they mean by "secure" is that after
you've given them the power to read and modify your data, they try
really hard not to let this power be abused. This turns out to be
difficult! Bugs, misconfigurations, or operator error can accidentally
expose your data to another customer or to the public, or can corrupt
your data. Criminals routinely gain illicit access to corporate
servers. Even more insidious is the fact that the employees themselves
sometimes violate customer privacy out of carelessness, avarice, or
mere curiousity. The most conscientious of these service providers
spend considerable effort and expense trying to mitigate these risks.
What we mean by "security" is something different. *The service
provider never has the ability to read or modify your data in the first
place -- never.* If you use Tahoe-LAFS, then all of the threats
described above are non-issues to you. Not only is it easy and
inexpensive for the service provider to maintain the security of your
data, but in fact they couldn't violate its security if they tried.
This is what we call *provider-independent security*.
This guarantee is integrated naturally into the Tahoe-LAFS storage
system and doesn't require you to perform a manual pre-encryption step
or cumbersome key management. (After all, having to do cumbersome
manual operations when storing or accessing your data would nullify one
of the primary benefits of using cloud storage in the first place --
convenience.)
Here's how it works:
.. image:: http://tahoe-lafs.org/~zooko/network-and-reliance-topology.png
A "storage grid" is made up of a number of storage servers. A storage
server has direct attached storage (typically one or more hard disks).
A "gateway" uses the storage servers and provides access to the
filesystem over HTTP(S) or (S)FTP.
Users do not rely on storage servers to provide *confidentiality* nor
*integrity* for their data -- instead all of the data is encrypted and
integrity-checked by the gateway, so that the servers can neither read
nor modify the contents of the files.
Users do rely on storage servers for *availability*. The ciphertext is
erasure-coded and distributed across ``N`` storage servers (the default
value for ``N`` is 10) so that it can be recovered from any ``K`` of
these servers (the default value of ``K`` is 3). Therefore only the
simultaneous failure of ``N-K+1`` (with the defaults, 8) servers can
make the data unavailable.
In the typical deployment mode each user runs her own gateway on her
own machine. This way she relies on her own machine for the
confidentiality and integrity of the data.
An alternate deployment mode is that the gateway runs on a remote
machine and the user connects to it over HTTPS or SFTP. This means
that the operator of the gateway can view and modify the user's data
(the user *relies on* the gateway for confidentiality and integrity),
but the advantage is that the user can access the filesystem with a
client that doesn't have the gateway software installed, such as an
Internet kiosk or cell phone.
Access Control
==============
There are two kinds of files: immutable and mutable. Immutable files
have the property that once they have been uploaded to the storage grid
they can't be modified. Mutable ones can be modified. A user can have
read-write access to a mutable file or read-only access to it (or no
access to it at all).
A user who has read-write access to a mutable file or directory can
give another user read-write access to that file or directory, or they
can give read-only access to that file or directory. A user who has
read-only access to a file or directory can give another user read-only
access to it.
When linking a file or directory into a parent directory, you can use a
read-write link or a read-only link. If you use a read-write link,
then anyone who has read-write access to the parent directory can gain
read-write access to the child, and anyone who has read-only access to
the parent directory can gain read-only access to the child. If you
use a read-only link, then anyone who has either read-write or
read-only access to the parent directory can gain read-only access to
the child.
For more technical detail, please see the `the doc page
<http://tahoe-lafs.org/trac/tahoe-lafs/wiki/Doc>`_ on the Wiki.
Get Started
===========
To use Tahoe-LAFS, please see `quickstart.rst <quickstart.rst>`_.
License
=======
You may use this package under the GNU General Public License, version
2 or, at your option, any later version. See the file `COPYING.GPL
<../COPYING.GPL>`_ for the terms of the GNU General Public License,
version 2.
You may use this package under the Transitive Grace Period Public
Licence, version 1 or, at your option, any later version. The
Transitive Grace Period Public Licence has requirements similar to the
GPL except that it allows you to wait for up to twelve months after you
redistribute a derived work before releasing the source code of your
derived work. See the file `COPYING.TGGPL <../COPYING.TGPPL.html>`_ for
the terms of the Transitive Grace Period Public Licence, version 1.
(You may choose to use this package under the terms of either licence,
at your option.)

7
docs/historical/historical_known_issues.txt
View File

@ -112,6 +112,7 @@ please ignore ERROR "Reactor was unclean" in test_system and
test_introducer. Upgrading to a newer version of Twisted or pyOpenSSL
will cause those false alarms to stop happening (as will downgrading
to an older version of either of those packages).
== issues in Tahoe v1.0.0, released 2008-03-25 ==
(Tahoe v1.0 was superceded by v1.1 which was released 2008-06-11.)
@ -127,7 +128,8 @@ write succeeded, when it in fact failed. This can cause data loss.
Upgrade client to v1.1, or make sure that servers are always able to
write to their local filesystem (including that there is space
available) as described in "issue 1" above.
available) as described in "server out of space when writing mutable
file" above.
=== server out of space when writing immutable file ===
@ -144,7 +146,8 @@ data loss.
Upgrading either or both of the client and the server to v1.1 will fix
this issue. Also it can be avoided by ensuring that the servers are
always able to write to their local filesystem (including that there
is space available) as described in "issue 1" above.
is space available) as described in "server out of space when writing
mutable file" above.
=== large directories or mutable files of certain sizes ===

2
docs/how_to_make_a_tahoe-lafs_release.rst
View File

@ -1,6 +1,6 @@
[ ] 1 update doc files: `<../relnotes.txt>`_, `<../CREDITS>`_, `<known_issues.rst>`_, `<../NEWS>`_. Add release name and date to top-most item in NEWS.
[ ] 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
[ ] 2 change `<quickstart.rst>`_ 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

15
docs/install.html
View File

@ -1,15 +0,0 @@
<!DOCtype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html lang="en">
<head>
<title>Getting Tahoe-LAFS</title>
<link rev="made" class="mailto" href="mailto:zooko[at]zooko[dot]com">
<meta name="description" content="how to get Tahoe-LAFS">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="keywords" content="tahoe-lafs secure decentralized filesystem installation">
<meta http-equiv="refresh" content="0;url=quickstart.html" />
</head>
<body>
<p>This page has moved to <a href="quickstart.html">quickstart.html</a>.</p>
</body>
</html>

98
docs/quickstart.html
View File

@ -1,98 +0,0 @@
<!DOCtype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html lang="en">
<head>
<style type="text/css">
p.p1 {font-size:85%;}
p.p1 {font-style:italic;}
</style>
<title>Getting Tahoe-LAFS</title>
<link rev="made" class="mailto" href="mailto:zooko[at]zooko[dot]com">
<meta name="description" content="how to get Tahoe-LAFS">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="keywords" content="tahoe-lafs secure decentralized filesystem installation">
</head>
<body>
<h1>About Tahoe-LAFS</h1>
<p> The homepage of Tahoe-LAFS is <a href="http://tahoe-lafs.org">
http://tahoe-lafs.org</a>. There is a one-page overview at <a href="about.html">
About Tahoe-LAFS</a>.
<h1>How To Get Tahoe-LAFS</h1>
<p class=p1>This has been verified to work on Windows, Mac, OpenSolaris,
and too many flavors of Linux and of *BSD to list. It's likely to work on
other platforms.</p>
<p class=p1><strong>WARNING!</strong> There are a few third-party
libraries that Tahoe-LAFS depends on that might not be easy to set up on
your platform. If the following instructions don't Just Work, please write
to <a href="http://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev">the
tahoe-dev mailing list</a> where fun, friendly, hackers will help you out!
You might also find clues in the Advanced Installation section below.</p>
<h2>Install Python</h2>
<p>Check if you already have an adequate version of Python installed by
running <cite>python --version</cite>. Python&nbsp;v2.4 (v2.4.4 or
greater), Python&nbsp;v2.5, Python&nbsp;v2.6, or Python&nbsp;v2.7 will
work. Python&nbsp;v3 does not work. On Windows, we recommend the use of
Python&nbsp;v2.6 (native, not Cygwin).</p>
<p>If you don't have one of these versions of Python installed, then
follow the instructions on
<a href="http://www.python.org/download/releases/2.6.6/">the Python
download page</a> to download and install Python&nbsp;v2.6. Make sure
that the path to the installation directory has no spaces in it (e.g. on
Windows, do not install Python in the "<tt>Program Files</tt>" directory).
</p>
<h2>Get Tahoe-LAFS</h2>
<p>Download the latest stable release, v1.8.2:</p>
<pre><a
href="http://tahoe-lafs.org/source/tahoe-lafs/releases/allmydata-tahoe-1.8.2.zip">http://tahoe-lafs.org/source/tahoe-lafs/releases/allmydata-tahoe-1.8.2.zip</a></pre>
<h2>Set Up Tahoe-LAFS</h2>
<p>Unpack the zip file and cd into the top-level directory.</p>
<p>Run <cite>python setup.py build</cite> to generate the <cite>tahoe</cite>
executable in a subdirectory of the current directory named <cite>bin</cite>.
This will download and build anything you need from various websites.</p>
<p>On Windows, the <cite>build</cite> step might tell you to open a new
Command Prompt (or, on XP and earlier, to log out and back in again).
This is needed the first time you set up Tahoe-LAFS on a particular
installation of Windows.</p>
<p>Optionally run <cite>python setup.py test</cite> to verify that it
passes all of its self-tests.</p>
<p>Run <cite>bin/tahoe --version</cite> (on Windows,
<cite>bin\tahoe --version</cite>) to verify that the executable tool prints
out the right version number.</p>
<h2>Run Tahoe-LAFS</h2>
<p>Now you are ready to deploy a decentralized filesystem. The
<cite>tahoe</cite> executable in the <cite>bin</cite> directory can
configure and launch your Tahoe-LAFS nodes.
See <a href="running.html">running.html</a> for instructions on how to do
that.</p>
<h2>Advanced Installation</h2>
<p>For optional features such as tighter integration with your operating
system's package manager, you can see the
<a href="http://tahoe-lafs.org/trac/tahoe/wiki/AdvancedInstall">AdvancedInstall</a>
wiki page. The options on that page are not necessary to use Tahoe-LAFS
and can be complicated, so we do not recommend following that page unless
you have unusual requirements for advanced optional features. For most
people, you should first follow the instructions on this page, and if that
doesn't work then ask for help by writing to
<a href="http://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev">the
tahoe-dev mailing list</a>.</p>
</body>
</html>

94
docs/quickstart.rst Normal file
View File

@ -0,0 +1,94 @@
==================
Getting Tahoe-LAFS
==================
Welcome to `the Tahoe-LAFS project <http://tahoe-lafs.org>`_, a secure,
decentralized, fault-tolerant storage system. `About Tahoe-LAFS
<about.rst>`_.
How To Get Tahoe-LAFS
=====================
This procedure has been verified to work on Windows, Mac, OpenSolaris,
and too many flavors of Linux and of BSD to list. It's likely to work
on other platforms.
In Case Of Trouble
------------------
There are a few 3rd party libraries that Tahoe-LAFS depends on that
might not be easy to set up on your platform. If the following
instructions don't Just Work without any further effort on your part,
then please write to `the tahoe-dev mailing list
<http://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev>`_ where
friendly hackers will help you out. You might also find clues in the
`Advanced Installation`_ section described below.
Install Python
--------------
Check if you already have an adequate version of Python installed by
running ``python -V``. Python v2.4 (v2.4.4 or greater), Python v2.5,
Python v2.6, or Python v2.7 will work. Python v3 does not work. On
Windows, we recommend the use of Python v2.6 (native, not Cygwin). If
you don't have one of these versions of Python installed, then follow
the instructions on `the Python download page
<http://www.python.org/download/releases/2.6.6/>`_ to download and
install Python v2.6. Make sure that the path to the installation
directory has no spaces in it (e.g. on Windows, do not install Python
in the "Program Files" directory).
If you are on Windows, you now must manually install the pywin32
package from `the pywin32 site
<http://sourceforge.net/projects/pywin32/files/>`_ before getting
Tahoe-LAFS. Make sure to get the correct file for the version of Python
you are using -- e.g. ending in "py2.6.exe" for Python v2.6. If using
64-bit Windows, the file should have "win-amd64" in its name.
Get Tahoe-LAFS
--------------
`Download the latest stable release, v1.8.1
<http://tahoe-lafs.org/source/tahoe-lafs/releases/allmydata-tahoe-1.8.1.zip>`_
Set Up Tahoe-LAFS
-----------------
Unpack the zip file and cd into the top-level directory.
Run ``python setup.py build`` to generate the ``tahoe`` executable in a
subdirectory of the current directory named ``bin``. This will download
and build anything you need from various websites.
On Windows, the ``build`` step might tell you to open a new Command
Prompt (or, on XP and earlier, to log out and back in again). This is
needed the first time you set up Tahoe-LAFS on a particular
installation of Windows.
Optionally run ``python setup.py test`` to verify that it passes all
of its self-tests.
Run ``bin/tahoe --version`` (on Windows, ``bin\tahoe --version``) to
verify that the executable tool prints out the right version number.
Run Tahoe-LAFS
--------------
Now you are ready to deploy a decentralized filesystem. The ``tahoe``
executable in the ``bin`` directory can configure and launch your
Tahoe-LAFS nodes. See `running.rst <running.rst>`_ for instructions on
how to do that.
Advanced Installation
---------------------
For optional features such as tighter integration with your operating
system's package manager, you can see the `AdvancedInstall
<http://tahoe-lafs.org/trac/tahoe/wiki/AdvancedInstall>`_ wiki page.
The options on that page are not necessary to use Tahoe-LAFS and can be
complicated, so we do not recommend following that page unless you have
unusual requirements for advanced optional features. For most people,
you should first follow the instructions on this page, and if that
doesn't work then ask for help by writing to `the tahoe-dev mailing
list <http://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev>`_.

150
docs/running.html
View File

@ -1,150 +0,0 @@
<!DOCtype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html lang="en">
<head>
<title>Running Tahoe-LAFS</title>
<link rev="made" class="mailto" href="mailto:zooko[at]zooko[dot]com">
<meta name="description" content="how to run Tahoe-LAFS">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="keywords" content="tahoe Tahoe-LAFS secure decentralized filesystem operation">
</head>
<body>
<h1>How To Run Tahoe-LAFS</h1>
<p>This is how to run a Tahoe-LAFS client to connect to an
existing grid, or how to set up a complete Tahoe-LAFS grid. First
you have to install the Tahoe-LAFS software, as documented
in <a href="install.html">install.html</a>.</p>
<p>The <code>tahoe</code> program in the <code>bin</code> directory is
used to create, start, and stop nodes. Each node lives in a separate base
directory, in which there is a configuration file named <code>tahoe.cfg</code>. Nodes
read and write files within this base directory.</p>
<p>A grid consists of a set of <em>storage nodes</em>
and <em>client nodes</em> (also known as <em>gateway nodes</em>)
running the Tahoe-LAFS code. There is also an <em>introducer
node</em> that is responsible for getting the other nodes talking
to each other. Which grid of storage servers your client will
connect to is determined solely by the introducer—if you configure
your node to connect to a certain introducer then your node will
only use those storage servers provided by that introducer. If you
configure your node to connect to a new introducer of your own
creation (see below), then your node will not connect to any
storage servers until you've created some storage servers and told them
to register themselves with that introducer.</p>
<p>If you're getting started we recommend you try connecting to
the <a href="http://tahoe-lafs.org/trac/tahoe-lafs/wiki/TestGrid">the
public test grid</a>—you will need to create only a gateway node
to do that. When you want to create your own grid you'll need to
create the introducer and several initial storage nodes (see the
note about small grids below).</p>
<p>If the Tahoe-LAFS <code>bin</code> directory is not on your PATH, then
in all the command lines below, specify the full path to <code>bin/tahoe</code>.</p>
<p>To construct a client node, run
"<code>tahoe create-client</code>", which will create <code>~/.tahoe</code> to be the
node's base directory. Acquire a copy of the <code>introducer.furl</code>
from the introducer and put it into this directory, then use
"<code>tahoe run</code>". After that, the node should be off and running. The first
thing it will do is connect to the introducer and get itself connected to
all other nodes on the grid. By default, "<code>tahoe create-client</code>"
creates a client-only node, that does not offer its disk space to other nodes.
To configure other behavior, use "<code>tahoe create-node</code>" or see
<a href="configuration.rst">configuration.rst</a>.</p>
<p>To construct an introducer, create a new base directory for it (the name
of the directory is up to you), <code>cd</code> into it, and run
"<code>tahoe create-introducer .</code>". Now run the introducer using
"<code>tahoe start .</code>". After it starts, it will write a file named
<code>introducer.furl</code> in that base directory. This file contains the
URL the other nodes must use in order to connect to this introducer.
(Note that "<code>tahoe run .</code>" doesn't work for introducers, this is a known
issue: <a href="http://allmydata.org/trac/tahoe-lafs/ticket/937">#937</a>.)</p>
<p>The "<code>tahoe run</code>" command above
will run the node in the foreground. On Unix, you can run it in the background
instead by using the "<code>tahoe start</code>" command.
To stop a node started in this way, use "<code>tahoe stop</code>".
<code>tahoe --help</code> gives a summary of all commands.</p>
<p>See <a href="configuration.rst">configuration.rst</a> for more
details about how to configure Tahoe-LAFS, including how to get other
clients to connect to your node if it is behind a firewall or NAT device.
<h3>A note about small grids</h3>
<p>By default, Tahoe-LAFS ships with the configuration parameter
<code>shares.happy</code> set to 7. If you are using Tahoe-LAFS on a
grid with fewer than 7 storage nodes, this won't work well for you
&mdash; none of your uploads will succeed. To fix this, see <a
href='configuration.rst'>configuration.rst</a> to learn how to set
<code>shares.happy</code> to a more suitable value for your
grid.</p>
<h2>Do Stuff With It</h2>
<p>This is how to use your Tahoe-LAFS node.</p>
<h3>The WUI</h3>
<p>Point your web browser to <a
href="http://127.0.0.1:3456">http://127.0.0.1:3456</a> &mdash; which is the URL
of the gateway running on your own local computer &mdash; to use your newly
created node.</p>
<p>Create a new directory (with the button labelled "create a directory").
Your web browser will load the new directory. Now if you want to be able
to come back to this directory later, you have to bookmark it, or otherwise
save a copy of the URL. If you lose URL to this directory, then you can never
again come back to this directory.</p>
<p>You can do more or less everything you want to do with a decentralized
filesystem through the WUI.</p>
<h3>The CLI</h3>
<p>Prefer the command-line? Run "<code>tahoe --help</code>" (the same
command-line tool that is used to start and stop nodes serves to navigate
and use the decentralized filesystem). To get started, create a new
directory and mark it as the 'tahoe:' alias by running "<code>tahoe
create-alias tahoe</code>". Once you've done that, you can do
"<code>tahoe ls tahoe:</code>" and "<code>tahoe cp LOCALFILE
tahoe:foo.txt</code>" to work with your filesystem. The Tahoe-LAFS CLI uses
similar syntax to the well-known scp and rsync tools. See <a
href="frontends/CLI.rst">CLI.rst</a> for more details.</p>
<p>As with the WUI (and with all current interfaces to Tahoe-LAFS), you are
responsible for remembering directory capabilities yourself. If you create
a new directory and lose the capability to it, then you cannot access that
directory ever again.</p>
<h3>The SFTP and FTP frontends</h3>
<p>You can access your Tahoe-LAFS grid via any <a href="http://en.wikipedia.org/wiki/SSH_file_transfer_protocol">SFTP</a> or
<a href="http://en.wikipedia.org/wiki/File_Transfer_Protocol">FTP</a> client.
See <a href="frontends/FTP-and-SFTP.rst">FTP-and-SFTP.rst</a> for how to set this up.
On most Unix platforms, you can also use SFTP to plug Tahoe-LAFS into your computer's
local filesystem via <code>sshfs</code>.
<p>The <a href="http://tahoe-lafs.org/trac/tahoe-lafs/wiki/SftpFrontend">SftpFrontend</a> page
on the wiki has more information about using SFTP with Tahoe-LAFS.</p>
<h3>The Web-API</h3>
<p>Want to program your Tahoe-LAFS node to do your bidding? Easy! See <a
href="frontends/webapi.rst">webapi.rst</a>.</p>
<h2>Socialize</h2>
<p>You can chat with other users of and hackers of this software on the
#tahoe-lafs IRC channel at <code>irc.freenode.net</code>, or on the <a
href="http://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev">tahoe-dev mailing list</a>.</p>
</body>
</html>

135
docs/running.rst Normal file
View File

@ -0,0 +1,135 @@
=====================
How To Run Tahoe-LAFS
=====================
Intro
=====
This is how to run a Tahoe-LAFS client or a complete Tahoe-LAFS grid.
First you have to install the Tahoe-LAFS software, as documented in
`quickstart.rst <quickstart.rst>`_.
The ``tahoe`` program in the ``bin`` directory is used to create,
start, and stop nodes. Each node lives in a separate base directory, in
which there is a configuration file named ``tahoe.cfg``. Nodes read and
write files within this base directory.
A grid consists of a set of *storage nodes* and *client nodes* running
the Tahoe-LAFS code. There is also an *introducer node* that is
responsible for getting the other nodes talking to each other.
If you're getting started we recommend you try connecting to
the `the public test grid
<http://tahoe-lafs.org/trac/tahoe-lafs/wiki/TestGrid>`_ as you only
need to create a client node. When you want to create your own grid
you'll need to create the introducer and several initial storage nodes
(see the note about small grids below).
If the Tahoe-LAFS ``bin`` directory is not on your PATH, then in all
the command lines below, specify the full path to ``bin/tahoe``.
To construct a client node, run "``tahoe create-client``", which will
create ``~/.tahoe`` to be the node's base directory. Acquire a copy of
the ``introducer.furl`` from the introducer and put it into this
directory, then use "``tahoe run``". After that, the node should be off
and running. The first thing it will do is connect to the introducer
and get itself connected to all other nodes on the grid. By default,
"``tahoe create-client``" creates a client-only node, that does not
offer its disk space to other nodes. To configure other behavior, use
"``tahoe create-node``" or see `configuration.rst <configuration.rst>`_.
To construct an introducer, create a new base directory for it (the
name of the directory is up to you), ``cd`` into it, and run
"``tahoe create-introducer .``". Now run the introducer using
"``tahoe start .``". After it starts, it will write a file named
``introducer.furl`` in that base directory. This file contains the URL
the other nodes must use in order to connect to this introducer. (Note
that "``tahoe run .``" doesn't work for introducers, this is a known
issue: `#937 <http://allmydata.org/trac/tahoe-lafs/ticket/937>`_.)
The "``tahoe run``" command above will run the node in the foreground.
On Unix, you can run it in the background instead by using the
"``tahoe start``" command. To stop a node started in this way, use
"``tahoe stop``". ``tahoe --help`` gives a summary of all commands.
See `configuration.rst <configuration.rst>`_ for more details about how
to configure Tahoe-LAFS, including how to get other clients to connect
to your node if it is behind a firewall or NAT device.
A note about small grids
------------------------
By default, Tahoe-LAFS ships with the configuration parameter
``shares.happy`` set to 7. If you are using Tahoe-LAFS on a
grid with fewer than 7 storage nodes, this won't work well for you
&mdash; none of your uploads will succeed. To fix this, see <a
href='configuration.rst'>configuration.rst</a> to learn how to set
``shares.happy`` to a more suitable value for your
grid.
Do Stuff With It
================
This is how to use your Tahoe-LAFS node.
The WUI
-------
Point your web browser to `http://127.0.0.1:3456
<http://127.0.0.1:3456>`_ -- which is the URL of the gateway running on
your own local computer -- to use your newly created node.
Create a new directory (with the button labelled "create a directory").
Your web browser will load the new directory. Now if you want to be
able to come back to this directory later, you have to bookmark it, or
otherwise save a copy of the URL. If you lose URL to this directory,
then you can never again come back to this directory.
You can do more or less everything you want to do with a decentralized
filesystem through the WUI.
The CLI
-------
Prefer the command-line? Run "``tahoe --help``" (the same command-line
tool that is used to start and stop nodes serves to navigate and use
the decentralized filesystem). To get started, create a new directory
and mark it as the 'tahoe:' alias by running
"``tahoe create-alias tahoe``". Once you've done that, you can do
"``tahoe ls tahoe:``" and "``tahoe cp LOCALFILE tahoe:foo.txt``" to
work with your filesystem. The Tahoe-LAFS CLI uses similar syntax to
the well-known scp and rsync tools. See `CLI.rst <frontends/CLI.rst>`_
for more details.
As with the WUI (and with all current interfaces to Tahoe-LAFS), you
are responsible for remembering directory capabilities yourself. If you
create a new directory and lose the capability to it, then you cannot
access that directory ever again.
The SFTP and FTP frontends
--------------------------
You can access your Tahoe-LAFS grid via any `SFTP
<http://en.wikipedia.org/wiki/SSH_file_transfer_protocol>`_ or `FTP
<http://en.wikipedia.org/wiki/File_Transfer_Protocol>`_ client.
See `FTP-and-SFTP.rst <frontends/FTP-and-SFTP.rst>`_ for how to set
this up. On most Unix platforms, you can also use SFTP to plug
Tahoe-LAFS into your computer's local filesystem via ``sshfs``.
The `SftpFrontend
<http://tahoe-lafs.org/trac/tahoe-lafs/wiki/SftpFrontend>`_ page on the
wiki has more information about using SFTP with Tahoe-LAFS.
The WAPI
--------
Want to program your Tahoe-LAFS node to do your bidding? Easy! See
`webapi.rst <frontends/webapi.rst>`_.
Socialize
=========
You can chat with other users of and hackers of this software on the
#tahoe-lafs IRC channel at ``irc.freenode.net``, or on the `tahoe-dev
mailing list
<http://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev>`_.

16
docs/write_coordination.html
View File

@ -1,16 +0,0 @@
<!DOCtype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html lang="en">
<head>
<title>Avoiding Write Collisions in Tahoe</title>
<link rev="made" class="mailto" href="mailto:zooko[at]zooko[dot]com">
<meta name="description" content="how to avoid write collisions in Tahoe">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="keywords" content="tahoe secure decentralized filesystem installation">
</head>
<body>
<h1>Write Collisions</h1>
<p>Tahoe does not provide locking of the mutable files and directories. If there is more than one simultaneous attempt to change a mutable file or directory, then an <cite>UncoordinatedWriteError</p> will result. This might, in rare cases, cause the file or directory contents to be accidentally deleted. The user is expected to ensure that there is at most one outstanding write or update request for a given file or directory at a time. One convenient way to accomplish this is to make a different file or directory for each person or process which wants to write.</p>
</body>
</html>

13
docs/write_coordination.rst Normal file
View File

@ -0,0 +1,13 @@
==================================
Avoiding Write Collisions in Tahoe
==================================
Tahoe does not provide locking of the mutable files and directories.
If there is more than one simultaneous attempt to change a mutable file
or directory, then an <cite>UncoordinatedWriteError</p> will result.
This might, in rare cases, cause the file or directory contents to be
accidentally deleted. The user is expected to ensure that there is at
most one outstanding write or update request for a given file or
directory at a time. One convenient way to accomplish this is to make
a different file or directory for each person or process which wants to
write.

8
relnotes.txt
View File

@ -4,7 +4,7 @@ The Tahoe-LAFS team is pleased to announce the immediate
availability of version 1.8.2 of Tahoe-LAFS, an extremely
reliable distributed storage system. Get it here:
http://tahoe-lafs.org/source/tahoe/trunk/docs/quickstart.html
http://tahoe-lafs.org/source/tahoe/trunk/docs/quickstart.rst
Tahoe-LAFS is the first distributed storage system to offer
"provider-independent security" — meaning that not even the
@ -12,7 +12,7 @@ operators of your storage servers can read or alter your data
without your consent. Here is the one-page explanation of its
unique security and fault-tolerance properties:
http://tahoe-lafs.org/source/tahoe/trunk/docs/about.html
http://tahoe-lafs.org/source/tahoe/trunk/docs/about.rst
The previous stable release of Tahoe-LAFS was v1.8.1, which was
released October 28, 2010 [1].
@ -92,7 +92,7 @@ INSTALLATION
Tahoe-LAFS works on Linux, Mac OS X, Windows, Cygwin, Solaris,
*BSD, and probably most other systems. Start with
"docs/quickstart.html" [7].
"docs/quickstart.rst" [7].
HACKING AND COMMUNITY
@ -150,7 +150,7 @@ San Francisco, California, USA
[4] http://tahoe-lafs.org/trac/tahoe/browser/docs/known_issues.rst
[5] http://tahoe-lafs.org/trac/tahoe/browser/COPYING.GPL
[6] http://tahoe-lafs.org/source/tahoe/trunk/COPYING.TGPPL.html
[7] http://tahoe-lafs.org/source/tahoe/trunk/docs/quickstart.html
[7] http://tahoe-lafs.org/source/tahoe/trunk/docs/quickstart.rst
[8] http://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev
[9] http://tahoe-lafs.org/trac/tahoe/roadmap
[10] http://tahoe-lafs.org/trac/tahoe/browser/CREDITS?rev=5000

2
setup.py
View File

@ -7,7 +7,7 @@
#
# This file is part of Tahoe-LAFS.
#
# See the docs/about.html file for licensing information.
# See the docs/about.rst file for licensing information.
import glob, os, stat, subprocess, sys, re

2
src/allmydata/mutable/common.py
View File

@ -25,7 +25,7 @@ class UncoordinatedWriteError(Exception):
return ("<%s -- You, oh user, tried to change a file or directory "
"at the same time as another process was trying to change it. "
" To avoid data loss, don't do this. Please see "
"docs/write_coordination.html for details.>" %
"docs/write_coordination.rst for details.>" %
(self.__class__.__name__,))
class UnrecoverableFileError(Exception):